home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / scd113.arc / MANUAL.DOC < prev    next >
Text File  |  1990-06-14  |  261KB  |  11,815 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                SoftC Database Library
  16.  
  17.                                   Reference Manual
  18.  
  19.  
  20.                                     Version 1.13
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                    Manual and Software Copyright 1988, 1989, 1990
  32.                                          by
  33.  
  34.  
  35.                                     SoftC, Ltd.
  36.                            16820 Third Street North East
  37.                              Ham Lake, Minnesota 55304
  38.                     Telephone (612) 434-6968  Fax (612) 780-8728
  39.  
  40.  
  41.  
  42.                                 ALL RIGHTS RESERVED
  43.  
  44.  
  45.  
  46.              This document describes version 1.13 of the SoftC Database
  47.                         Library, released in February, 1990.
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                       SoftC Database Library License Agreement
  74.  
  75.  
  76.             This License  Agreement  (Agreement)  is  between  you  (the
  77.             Customer) and  SoftC, Ltd.  (SoftC).  The Agreement pertains
  78.             to the  SoftC Database  Library, including  the object  code
  79.             libraries, sample  programs, source  code (if provided), and
  80.             modifications and/or  recompilations of the source code (the
  81.             Product), and the documentation.
  82.  
  83.             In exchange  for the non-exclusive right to use the Product,
  84.             the Customer agrees to the following terms.
  85.  
  86.             OWNERSHIP AND LIMITED LICENSE: The Product is owned by SoftC
  87.             and  is   protected  by   applicable  copyright   laws   and
  88.             international treaty  provisions.  The Customer is granted a
  89.             non-exclusive  license  to  use  the  Product  on  a  single
  90.             computer system (i.e., with a single CPU) or network node at
  91.             a time.
  92.  
  93.             COPYING AND  USE: The Customer may make backup copies of the
  94.             Product, but  may install  and use  the  Product  (including
  95.             modifications and/or recompilations of the software) on only
  96.             one computer or network node at a time.  This means that the
  97.             Product may  be used  by any  number of  people and  may  be
  98.             freely moved  from one computer location to another, so long
  99.             as there  is no possibility of it being used at one location
  100.             while it is being used at another.
  101.  
  102.             PRODUCT CODE  AND DERIVATIVE  WORKS:  In  exchange  for  the
  103.             benefit from  having access  to  the  Product  the  Customer
  104.             agrees to protect the copyright and other proprietary rights
  105.             of SoftC.   Such protection includes, but is not limited to,
  106.             a) the  Customer not  disclosing  the  code  (object  and/or
  107.             source) and  the way  it functions to any party not bound by
  108.             this Agreement,  b) the  Customer not allowing any party not
  109.             bound by  this Agreement  to copy  or  use  the  Product  or
  110.             documentation in  violation of  this Agreement  and  c)  the
  111.             Customer may  not disclose,  allow disclosure,  transmit, or
  112.             allow transmission,  either directly  or indirectly,  of the
  113.             source code  to any  third party  without the  prior written
  114.             consent of SoftC.  The Customer may modify and/or re-compile
  115.             the Product source code solely for the Customer's use.  Such
  116.             modified and/or  re-compiled  versions,  regardless  of  the
  117.             extent  of  the  modifications  or  the  compiler  versions,
  118.             operating systems, or computer systems used, are part of the
  119.             same Product  under this  Agreement  and  shall  remain  the
  120.             property of  SoftC subject  to  the  same  limitations  upon
  121.             transfer or  use as  the original Product.  The Customer may
  122.             reproduce and  distribute application programs created using
  123.             the Product  without  additional  licenses  or  fees.    Any
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.             modification of  the Product  source code  resulting  in  an
  140.             application or  derivative work  intended  for  distribution
  141.             requires prior written permission from SoftC and may require
  142.             additional terms and fees.
  143.  
  144.             TRANSFER: The  Customer  may  transfer  this  Agreement  and
  145.             Product along  with  all  originals,  any  copies,  and  the
  146.             documentation to  another party  provided  that  such  party
  147.             agrees in  writing to  be legally bound by these terms.  The
  148.             Customer's rights  shall terminate  upon  transfer  and  the
  149.             Customer agrees  to discontinue  immediately the  use of and
  150.             destroy any  and all  retained copies  of the  Product  upon
  151.             transfer.   The software  source code  if provided under the
  152.             license is not transferrable.
  153.  
  154.             LIMITED WARRANTY:   The  physical diskette(s)  and  physical
  155.             documentation  are  warranted  to  be  free  of  defects  in
  156.             materials and  workmanship for  a period  of sixty (60) days
  157.             from the  date of  original purchase.   For the same period,
  158.             the software  is warranted  against significant  errors that
  159.             make it  unusable for  the  operating  system  and  compiler
  160.             version originally  provided by  SoftC.    If  the  Customer
  161.             notifies SoftC within this 60 day period, SoftC will replace
  162.             any defective  diskette and/or  documentation.   SoftC  will
  163.             attempt to  correct or  help the Customer to avoid errors in
  164.             the software  with efforts  that SoftC  believes suitable to
  165.             the problem, or at SoftC's option, authorize a refund of the
  166.             Customer's  license   fee.     OTHER  THAN   THE   FOREGOING
  167.             WARRANTIES, SOFTC,  LTD. MAKES  NO  WARRANTIES,  EXPRESS  OR
  168.             IMPLIED, AND  SPECIFICALLY DISCLAIMS  ANY IMPLIED WARRANTIES
  169.             OF MERCHANTABILITY  OR FITNESS  FOR ANY  PARTICULAR PURPOSE.
  170.             SOFTC, LTD.  FURTHER RESERVES  THE RIGHT  TO MAKE CHANGES TO
  171.             THE SPECIFICATIONS  OF THE  PRODUCT  WITHOUT  OBLIGATION  TO
  172.             NOTIFY ANY PERSON OR ORGANIZATION OF SUCH CHANGES.
  173.  
  174.             LIMITATION OF  LIABILITY: The  Customer's sole  remedies are
  175.             set forth  in the  warranty clause above.  SoftC's liability
  176.             for damages  shall not exceed SoftC's suggested retail price
  177.             for the  Product.   In no event will SoftC be liable for any
  178.             special, incidental  or consequential  damages even if SoftC
  179.             has been advised of the possibility of the same.
  180.  
  181.             SUPPORT:   Product support, updates, fixes, enhancements, if
  182.             and as  they become available, may be offered for a separate
  183.             charge, but  SoftC has  no obligation  to provide  any  such
  184.             support, updates,  fixes, or  enhancements to  the  Product.
  185.             SoftC may  at its  sole discretion  provide  or  discontinue
  186.             support to  specific customers  on separate terms determined
  187.             solely by SoftC.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.             EXPORT:   The Customer  agrees not  to allow  the Product or
  206.             applications created using the Product to be sent to or used
  207.             in any  other country  except in  compliance with applicable
  208.             U.S. laws  and regulations.  If the Customer needs advice on
  209.             such export laws and regulations, the Customer shall contact
  210.             the  U.S.   Department   of   Commerce,   Export   Division,
  211.             Washington, DC 20230, U.S.A. for clarification.
  212.  
  213.             LICENSE TERMINATION:   This  Agreement shall  terminate upon
  214.             the transfer  of the  Product or  upon breach of any term of
  215.             this Agreement  by the  Customer.   The Customer shall cease
  216.             use of  the Product  upon termination.   In  the event  that
  217.             Customer has  received source  code for  the  Product,  upon
  218.             written request  by SoftC,  Customer shall  provide  written
  219.             certification by  an officer  of Customer that all copies of
  220.             the source code have been returned or destroyed.
  221.  
  222.             GOVERNING LAW:  This Agreement shall be governed by the laws
  223.             of the  State of  Minnesota.    If  any  provision  of  this
  224.             Agreement is  found void, invalid, or unenforceable, it will
  225.             not affect  the validity  of the  balance of  the Agreement,
  226.             which shall  remain valid  and enforceable  according to its
  227.             terms.  In the event any remedy herein is determined to have
  228.             failed  of   its  essential   purpose,  all  limitations  of
  229.             liability and  exclusion of  damages set  forth herein shall
  230.             remain in  full force  and effect.  This  Agreement  may  be
  231.             modified only  in writing  by the Customer and an authorized
  232.             representative of  SoftC.   Reasonable attorneys'  fees  and
  233.             court costs  shall be awarded to the prevailing party in any
  234.             action brought  in connection  with an alleged breach of the
  235.             terms of this Agreement.
  236.  
  237.             U.S.  GOVERNMENT   RESTRICTED  RIGHTS:    The  software  and
  238.             documentation are  provided with  RESTRICTED RIGHTS.    Use,
  239.             duplication, or  disclosure by  the Government is subject to
  240.             restrictions as  set forth in subparagraph (c)(1)(ii) of the
  241.             Rights in  Technical Data  and Computer  Software clause  at
  242.             52.227-7013. Contractor/manufacturer is SoftC, Ltd.
  243.  
  244.             ACCEPTANCE OF AGREEMENT:  The licensed use of the Product is
  245.             expressly conditioned  upon  the  Customer's  acceptance  of
  246.             these terms.   The  Customer may  accept these terms only by
  247.             signing  and  returning  the  Registration  Form.    SoftC's
  248.             acceptance of  these terms is represented by shipment of the
  249.             Product.
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                   Table Of Contents
  269.  
  270.  
  271.  
  272.             Chapter 1 Introduction......................................... 1
  273.                Registration................................................ 2
  274.                Shareware................................................... 2
  275.                Typographic Conventions..................................... 3
  276.                Trademarks.................................................. 3
  277.                Support and Updates......................................... 3
  278.  
  279.             Chapter 2 Before You Begin..................................... 4
  280.                The READ.ME File............................................ 4
  281.                Library Files............................................... 4
  282.                Installing SoftC on Your System............................. 5
  283.                SoftC Applications.......................................... 6
  284.                Compiling with Turbo C...................................... 7
  285.                Compiling with Microsoft C.................................. 7
  286.                Recompiling the Database Libraries.......................... 8
  287.                Function Naming Conventions................................. 9
  288.  
  289.             Chapter 3 A Database Tutorial................................. 10
  290.                Sequential Files........................................... 10
  291.                Random Access Files........................................ 10
  292.                Keys....................................................... 11
  293.                ISAM and B-trees........................................... 11
  294.                Basic Rules................................................ 12
  295.                Data File Functions........................................ 12
  296.                Data Record I/O............................................ 13
  297.                Data Field I/O............................................. 13
  298.                Memo File Functions........................................ 14
  299.                Index File Functions....................................... 15
  300.                Index Page Functions....................................... 16
  301.                Index Key Functions........................................ 16
  302.  
  303.             Chapter 4 Clock & Calendar Functions.......................... 17
  304.                Date String to String Conversion........................... 17
  305.                Date String to Numeric Conversion.......................... 17
  306.                Date Numeric to String Conversion.......................... 17
  307.                Date String Calculations................................... 18
  308.                Date Validation and Testing................................ 18
  309.                Time String to Numeric Conversion.......................... 18
  310.                Time Numeric to String Conversion.......................... 18
  311.                Time String Calculations................................... 18
  312.                Time Validation............................................ 18
  313.  
  314.             Chapter 5 Miscellaneous Functions............................. 19
  315.                Program Initialization..................................... 19
  316.                Program Termination........................................ 19
  317.                Library Version............................................ 19
  318.                Errors and Warnings........................................ 19
  319.  
  320.             Chapter 6 The SoftC Database Library.......................... 21
  321.                sccday..................................................... 23
  322.  
  323.  
  324.  
  325.                                           v
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                   TABLE OF CONTENTS
  335.  
  336.  
  337.                sccddiff................................................... 24
  338.                sccdl2s.................................................... 26
  339.                sccdn2s.................................................... 27
  340.                sccdperm................................................... 29
  341.                sccdpermi.................................................. 31
  342.                sccds2l.................................................... 33
  343.                sccds2n.................................................... 34
  344.                sccdvalid.................................................. 36
  345.                sccdxlat................................................... 37
  346.                sccleap.................................................... 39
  347.                sccleapi................................................... 40
  348.                sccmonth................................................... 41
  349.                scctdiff................................................... 43
  350.                scctn2s.................................................... 45
  351.                sccts2n.................................................... 47
  352.                scctvalid.................................................. 49
  353.                scddclose.................................................. 50
  354.                scddcreate................................................. 52
  355.                scddcreatex................................................ 55
  356.                scddinfo................................................... 58
  357.                scddopen................................................... 60
  358.                scddopenx.................................................. 62
  359.                scddsize................................................... 65
  360.                scdfget.................................................... 66
  361.                scdfgets................................................... 68
  362.                scdfgetsx.................................................. 70
  363.                scdfgett................................................... 72
  364.                scdfgettx.................................................. 74
  365.                scdfgetx................................................... 76
  366.                scdfinfo................................................... 78
  367.                scdfnam2no................................................. 80
  368.                scdfput.................................................... 82
  369.                scdfputs................................................... 84
  370.                scdfputsx.................................................. 86
  371.                scdfputt................................................... 88
  372.                scdfputtx.................................................. 90
  373.                scdfputx................................................... 92
  374.                scdinit.................................................... 94
  375.                scdkadd.................................................... 96
  376.                scdkcur.................................................... 98
  377.                scdkdate.................................................. 100
  378.                scdkdatex................................................. 101
  379.                scdkdel................................................... 103
  380.                scdkfind.................................................. 105
  381.                scdkfirst................................................. 107
  382.                scdklast.................................................. 109
  383.                scdkmake.................................................. 111
  384.                scdkmakex................................................. 114
  385.                scdknext.................................................. 116
  386.                scdkprev.................................................. 119
  387.                scdnclose................................................. 121
  388.  
  389.  
  390.  
  391.                                          vi
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                   TABLE OF CONTENTS
  401.  
  402.  
  403.                scdncreate................................................ 122
  404.                scdnexpr.................................................. 124
  405.                scdninfo.................................................. 126
  406.                scdnopen.................................................. 128
  407.                scdpinfo.................................................. 130
  408.                scdpnum................................................... 131
  409.                scdrclear................................................. 133
  410.                scdrcopy.................................................. 135
  411.                scdrdel................................................... 137
  412.                scdrget................................................... 139
  413.                scdrinfo.................................................. 141
  414.                scdrput................................................... 143
  415.                scdrundel................................................. 145
  416.                scdtclose................................................. 147
  417.                scdtcreate................................................ 148
  418.                scdterm................................................... 149
  419.                scdtinfo.................................................. 150
  420.                scdtopen.................................................. 152
  421.                scdvers................................................... 154
  422.                sceclr.................................................... 155
  423.                scemsg.................................................... 157
  424.  
  425.             Appendix A Result Codes and Messages......................... 158
  426.                Warning Codes and Messages................................ 158
  427.                Error Codes and Messages.................................. 159
  428.                Other Messages............................................ 164
  429.  
  430.             Appendix B Address List Demo Program......................... 165
  431.  
  432.             Appendix C Diskette TOC Demo Program......................... 167
  433.  
  434.             Index........................................................ 168
  435.             
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.                                          vii
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.           
  467.  
  468.  
  469.             Chapter 1
  470.  
  471.  
  472.             Introduction
  473.  
  474.  
  475.  
  476.  
  477.             C is  generally considered  to be a "bare-bones" language. A
  478.             way  to  put  some  flesh  on  those  bones  is  to  develop
  479.             generalized functions  (extensions) which  may be  reused in
  480.             many programs.  The presence  of these  functions  can  make
  481.             programming a  quick and  simple task.  The absence of these
  482.             language extensions  can mean  many hours lost "re-inventing
  483.             the wheel".
  484.  
  485.  
  486.             Few programmers  have the time required to develop and debug
  487.             such a  library  of  functions.  This  is  where  the  SoftC
  488.             Database Library  comes in.  This library is a collection of
  489.             functions designed  to make  your applications  quicker  and
  490.             easier to code and test. With the library you can spend time
  491.             on your application not on developing tools.
  492.  
  493.  
  494.             There also  is a  benefit to  using  functions  found  in  a
  495.             toolkit library  versus using  the functions  found in  your
  496.             compiler's library.  It may  seem trivial,  but if  you ever
  497.             decide to  change compilers  you will find that it will take
  498.             many  hours   to  convert  your  source  to  match  the  new
  499.             compiler's syntax. Using a generic toolkit such as the SoftC
  500.             Database Library will eliminate that effort.
  501.  
  502.  
  503.             The SoftC  Database Library  adds powerful  capabilities  to
  504.             your function library:
  505.  
  506.  
  507.                  -dBASEIII+ data, memo, and index file functions
  508.                  -dBASEIV data file functions
  509.                  -date and time manipulation and calculation
  510.  
  511.  
  512.             The  SoftC  Database  Library  is  intended  for  use  as  a
  513.             supplement to  your compiler's object libraries. It contains
  514.             seventy-three  user   functions.  Its   focus  is  dBASEIII+
  515.             compatible  data,   memo,  and   index   file   manipulation
  516.             functions. The  data file functions are also compatible with
  517.             dBASEIV files.  The clock/calendar functions have been added
  518.             to enhance the core dBASE routines. The library is currently
  519.  
  520.  
  521.  
  522.  
  523.                                           1
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                               CHAPTER 1, INTRODUCTION
  533.  
  534.  
  535.             available for  Turbo  C  2.0  and  Microsoft  C  5.1.  These
  536.             routines were written entirely in C.
  537.  
  538.  
  539.             Registration
  540.  
  541.             If you  find this  library useful,  you  are  encouraged  to
  542.             register.   Refer to  ORDER.DOC for  registration fees.   To
  543.             register,  read   the  license  agreement,  print  the  file
  544.             ORDER.DOC, and mail the completed form to:
  545.  
  546.  
  547.                                     SoftC, Ltd.
  548.                               16820 Third Street N.E.
  549.                               Ham Lake, MN 55304  USA
  550.  
  551.  
  552.             Shareware
  553.  
  554.             This library  is "shareware"  (user supported  software) NOT
  555.             "public domain",    which  means  that  the  SoftC  Database
  556.             Library (including the demonstration program - SOFTC113.EXE)
  557.             is the  copyrighted property of SoftC, Ltd. Registered users
  558.             are legally  bound by  the terms and conditions set forth in
  559.             the license  agreement.   Everyone is  granted the  right to
  560.             make copies and to freely share the UNMODIFIED demonstration
  561.             program.
  562.  
  563.  
  564.             The shareware  concept  is  an  attempt  to  provide  useful
  565.             software at low cost.  The expense of offering a new product
  566.             by conventional  means is  quite high  and thus  discourages
  567.             many independent authors and small companies from developing
  568.             and promoting  their ideas.   Shareware  is  an  attempt  to
  569.             develop a  new  marketing  channel  where  products  can  be
  570.             introduced at minimum cost.
  571.  
  572.  
  573.             Everyone will benefit if shareware works.  The user benefits
  574.             by having quality products at low cost, and by being able to
  575.             test software  thoroughly before  purchasing it.  The author
  576.             benefits by  being able  to enter  the  commercial  software
  577.             market without the need of large amounts of venture capital.
  578.  
  579.  
  580.             But it can only work with your support. If you obtain a user
  581.             supported product  from a  friend or coworker, and are still
  582.             using it  after a  few of  weeks, then it is obviously worth
  583.             something to you and you should register it.
  584.  
  585.  
  586.  
  587.  
  588.  
  589.                                           2
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                               CHAPTER 1, INTRODUCTION
  599.  
  600.  
  601.             Typographic Conventions
  602.  
  603.             []             Square brackets enclose optional data.
  604.             Boldface       SoftC Database Library function names (such
  605.                            as scdinit) and structure names when they
  606.                            appear in text (but not in program examples).
  607.             Underline      indicate variable names "identifiers" which
  608.                            appear in text.
  609.  
  610.  
  611.             Trademarks
  612.  
  613.             Clipper is a registered trademark of Nantucket Software.
  614.             dBASE, dBASEIII, and dBASEIV are registered trademarks of
  615.             Ashton-Tate.
  616.             Microsoft is a registered trademark of Microsoft
  617.             Corporation.
  618.             SoftC is a trademark of SoftC, Ltd.
  619.             Turbo C is a registered trademark of Borland International.
  620.  
  621.  
  622.             Support and Updates
  623.  
  624.             Technical advice  and technical  support will  be offered to
  625.             registered users  only.    Registered  users  will  also  be
  626.             notified when updates and new products are available.
  627.  
  628.  
  629.             We can be contacted by:
  630.  
  631.  
  632.                       mail      SoftC, Ltd.
  633.                                      16820 Third Street NE
  634.                                      Ham Lake, MN 55304  USA
  635.                       telephone (612) 434-6968
  636.                                      after 6pm Central Time
  637.                       modem     at above number (use voice first so that
  638.                                      we can set up the modem).
  639.                       GEnie     "K.SCHUMANN"
  640.                       CompuServ      73667,3420.
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.                                           3
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.           
  665.  
  666.  
  667.             Chapter 2
  668.  
  669.  
  670.             Before You Begin
  671.  
  672.  
  673.  
  674.  
  675.             This  chapter   supplies  instructions  for  installing  the
  676.             library on your hard disk and compiling the source.
  677.  
  678.  
  679.             The READ.ME File
  680.  
  681.             For last  minute update  information not  contained in  this
  682.             documentation, and/or a brief description of what's new with
  683.             this release please read the READ.ME file.
  684.  
  685.  
  686.             Library Files
  687.  
  688.             The SoftC  Database Library  is distributed in several self-
  689.             extracting  archive   programs.  The  demonstration  program
  690.             (SOFTC113.EXE) contains  eight (8) files (you are encouraged
  691.             to freely  share this  completely  unmodified  program  with
  692.             others):
  693.  
  694.  
  695.                  DEMO1.C             DEMO2.C
  696.                  LICENSE.DOC         MANUAL.DOC
  697.                  ORDER.DOC           SC_BASE.H
  698.                  SCDMC50S.LIB        SCDTC20S.LIB
  699.  
  700.  
  701.             The source  code archive  (SOURCE.EXE), for users registered
  702.             at that level, contains fifty-eight (58) files:
  703.  
  704.  
  705.                  CDAY.C              CDDIFF.C
  706.                  CDL2S.C             CDN2S.C
  707.                  CDPERM.C            CDS2L.C
  708.                  CDS2N.C             CDVALID.C
  709.                  CDXLAT.C            CLEAP.C
  710.                  CMONTH.C            CTDIFF.C
  711.                  CTN2S.C             CTS2N.C
  712.                  CTVALID.C           DDCREATE.C
  713.                  DDINFO.C            DDOPEN.C
  714.                  DDSIZE.C            DFGET.C
  715.                  DFGETT.C            DFINFO.C
  716.                  DFNAM2NO.C          DFPUT.C
  717.                  DFPUTT.C            DINIT.C
  718.  
  719.  
  720.  
  721.                                           4
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                             CHAPTER 2, BEFORE YOU BEGIN
  731.  
  732.  
  733.                  DKADD.C             DKCUR.C
  734.                  DKDATE.C            DKDEL.C
  735.                  DKFIND.C            DKFIRST.C
  736.                  DKLAST.C            DKMAKE.C
  737.                  DKNEXT.C            DKPREV.C
  738.                  DNCREATE.C          DNEXPR.C
  739.                  DNINFO.C            DNOPEN.C
  740.                  DPGET.C             DPINFO.C
  741.                  DPNUM.C             DPPUT.C
  742.                  DRCLEAR.C           DRCOPY.C
  743.                  DRDEL.C             DRGET.C
  744.                  DRINFO.C            DRPUT.C
  745.                  DRUNDEL.C           DTCREATE.C
  746.                  DTINFO.C            DTOPEN.C
  747.                  DVERS.C             EMSG.C
  748.                  SC_BASE.NTL         SC_BASE.RSP
  749.                  MSCLIB.BAT          TCLIB.BAT
  750.  
  751.  
  752.             The  Turbo   C  object  code  library  archive  (TCLIBS.EXE)
  753.             contains the following eight (8) files:
  754.  
  755.  
  756.                  DEMO1.C             DEMO2.C
  757.                  SC_BASE.H           SCDTC20S.LIB
  758.                  SCDTC20M.LIB        SCDTC20C.LIB
  759.                  SCDTC20L.LIB        SCDTC20H.LIB
  760.  
  761.  
  762.             The Microsoft  C and  Quick C  object code  library  archive
  763.             (MSCLIBS.EXE) contains the following eight (8) files:
  764.  
  765.  
  766.                  DEMO1.C             DEMO2.C
  767.                  SC_BASE.H           SCDMC50S.LIB
  768.                  SCDMC50M.LIB        SCDMC50C.LIB
  769.                  SCDMC50L.LIB        SCDMC50H.LIB
  770.  
  771.  
  772.             Installing SoftC on Your System
  773.  
  774.             The SoftC  Database Library   source code is compatible with
  775.             all of  the compilers  which we  support.  The  object  code
  776.             provided is for a specific C compiler.
  777.  
  778.  
  779.             Many compiler  manufacturers  suggest  a  certain  directory
  780.             setup to enable the compiler to find the header, object, and
  781.             library files.  Rather than  trying to  explain the  various
  782.             manufacturers suggested  directory setups,  we will  explain
  783.             what files are required and where they are often located.
  784.  
  785.  
  786.  
  787.                                           5
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                             CHAPTER 2, BEFORE YOU BEGIN
  797.  
  798.  
  799.             The library header files need to be placed where they can be
  800.             found by  your compiler.  In many cases this is in a special
  801.             "INCLUDE" directory.  Other times they are placed where your
  802.             source code  is found.  We would suggest that they be placed
  803.             where the header files for your compiler are located.
  804.  
  805.  
  806.             Your linker  will need  to be  able to find the SoftC object
  807.             code libraries.  It is  suggested that these be placed where
  808.             the run-time libraries for your compiler are found.
  809.  
  810.  
  811.             The name  of the  library defines  the compiler manufacturer
  812.             and version, and the memory model for which it was compiled.
  813.             All library  names begin with "SCD". The next few characters
  814.             specify the  compiler manufacturer  and  version.  The  last
  815.             character defines the memory model.
  816.  
  817.  
  818.             For example  SCDTC20S.LIB is  the small memory model library
  819.             for Borland's Turbo C compiler (version 2.0x).
  820.  
  821.  
  822.             SoftC Applications
  823.  
  824.             A typical application skeleton has the following form:
  825.  
  826.  
  827.  
  828.             #include <sc_base.h>
  829.             
  830.             /* global declarations */
  831.             
  832.             void main()
  833.             {
  834.               /* local declarations */
  835.             
  836.               scdinit(15);
  837.               .
  838.               .
  839.               .
  840.               /* body of application */
  841.               .
  842.               .
  843.               .
  844.               scdterm();
  845.             }
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.                                           6
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                             CHAPTER 2, BEFORE YOU BEGIN
  863.  
  864.  
  865.             
  866.  
  867.  
  868.             The scdinit  function must  be the  first function called in
  869.             your application  and IT  MUST BE CALLED ONLY ONCE. The last
  870.             function should be scdterm. This is not a requirement but it
  871.             is good  programming practice.  This function should also be
  872.             called only once. See the descriptions of these functions in
  873.             the library reference section of this manual.
  874.  
  875.  
  876.             Compiling with Turbo C
  877.  
  878.             Turbo  C  provides  two  ways  of  compiling  programs:  the
  879.             integrated environment  and the  command  line  version.  In
  880.             order to  use the SoftC Database Library with the integrated
  881.             environment  a   project  file   must  be  created  and  the
  882.             appropriate library must be specified in that file:
  883.  
  884.  
  885.  
  886.             myprog              /* your program name */
  887.             scdtc20s.lib        /* the desired SoftC Database library */
  888.  
  889.  
  890.  
  891.  
  892.  
  893.             
  894.  
  895.  
  896.             To use  the library  with the  command line  compiler simply
  897.             include the library name in the file name list:
  898.  
  899.  
  900.  
  901.             tcc -ml -I<header_file_path> -L<lib_file_path> myprog
  902.             scdtc20s.lib
  903.  
  904.  
  905.  
  906.  
  907.  
  908.             
  909.  
  910.  
  911.             Compiling with Microsoft C
  912.  
  913.             To use  the library  with Microsoft's  command line compiler
  914.             simply include the library name in the file name list:
  915.  
  916.  
  917.  
  918.  
  919.                                           7
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                             CHAPTER 2, BEFORE YOU BEGIN
  929.  
  930.  
  931.             cl /AL /Zp myprog scdmc51s.lib
  932.  
  933.  
  934.  
  935.  
  936.  
  937.             
  938.  
  939.  
  940.             Recompiling the Database Libraries
  941.  
  942.             If you  modify a  SoftC Database Library source module, then
  943.             that module  and  any  related  modules  (if  any)  must  be
  944.             recompiled and replaced in the libraries. The library source
  945.             code is compiled just like any other program.
  946.  
  947.  
  948.             Turbo C command line:
  949.  
  950.  
  951.  
  952.             tcc -c -ml -I<header_file_path> -f *.c
  953.  
  954.  
  955.  
  956.  
  957.  
  958.             
  959.  
  960.  
  961.             Microsoft C command line:
  962.  
  963.  
  964.  
  965.             cl /AL /c /Zp /W3 *.c
  966.  
  967.  
  968.  
  969.  
  970.  
  971.             
  972.  
  973.  
  974.             Refer to  your compiler  documentation for  instructions for
  975.             replacing modules  in libraries.  Batch files  are  included
  976.             with the  source  code  to  assist  you  in  rebuilding  the
  977.             libraries.
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.                                           8
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                             CHAPTER 2, BEFORE YOU BEGIN
  995.  
  996.  
  997.             Function Naming Conventions
  998.  
  999.             All of  the SoftC  Database Library functions begin with the
  1000.             letters  "sc".  This  is  to  differentiate  them  from  the
  1001.             standard library functions.
  1002.  
  1003.  
  1004.             "scc"     clock/calendar functions
  1005.  
  1006.                  "sccd"    date or calendar functions
  1007.                  "scct"    time functions
  1008.  
  1009.  
  1010.             "scd"     dBASE file functions
  1011.  
  1012.                  "scdd"    data file functions (open, close, etc.)
  1013.                  "scdf"    data field functions
  1014.                  "scdr"    data record functions (write, read, delete,                           etc.)
  1015.  
  1016.                  "scdn"    index file functions (open, close, etc.)
  1017.                  "scdk"    index key functions (add, delete, etc.)
  1018.                  "scdp"    index page functions
  1019.  
  1020.                  "scdt"    memo file functions (open, close, etc.)
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.                                           9
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.           
  1061.  
  1062.  
  1063.             Chapter 3
  1064.  
  1065.  
  1066.             A Database Tutorial
  1067.  
  1068.  
  1069.  
  1070.  
  1071.             Most applications  need to do some file I/O operations. Your
  1072.             C compiler  provides you  with basic functions to do general
  1073.             file I/O.  But many  cases will arise when you need to use a
  1074.             database within your application. The SoftC Database Library
  1075.             provides functions  to enable  you to integrate your program
  1076.             and dBASEIII  compatible data,  memo, and  index files,  and
  1077.             dBASEIV compatible data files.
  1078.  
  1079.  
  1080.             For those of you who may be unfamiliar with databases, think
  1081.             of a  filing cabinet filled with folders of invoices ordered
  1082.             alphabetically by  company name.  If we  wish  to  put  this
  1083.             information "on  computer" we have two choices for data file
  1084.             I/O: a simple sequential file, or a random access file.
  1085.  
  1086.  
  1087.             Sequential Files
  1088.  
  1089.             The concept of using a sequential file to store invoice data
  1090.             by company  name is very simple. Just enter the data as it's
  1091.             found in  the filing cabinet. To access the information just
  1092.             begin reading  at the  start of  the file and continue until
  1093.             finished. As  you can  see  the  time  required  to  find  a
  1094.             specific record  greatly increases  as more and more records
  1095.             are added to the file. Also the act of adding information to
  1096.             the file  while trying  to keep  it  in  alphabetical  order
  1097.             becomes very  time consuming  due  to  the  fact  that  many
  1098.             existing records will have to be moved in order to make room
  1099.             for the new record.
  1100.  
  1101.  
  1102.             Random Access Files
  1103.  
  1104.             By using  random access techniques it becomes much easier to
  1105.             access any  particular data  record. All that is required is
  1106.             the desired  record number  and you  can seek  to the proper
  1107.             location within  the data  file. But  how do  you know which
  1108.             record number  to use?  And what about adding records in the
  1109.             middle of  the data  file? dBASE  uses keys  and an  indexed
  1110.             lookup system called ISAM to solve both of these problems.
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.                                          10
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.                            CHAPTER 3, A DATABASE TUTORIAL
  1127.  
  1128.  
  1129.             Keys
  1130.  
  1131.             Keys are  generally comprised  of  one  or  more  pieces  of
  1132.             information (data  fields) found  in a  data record.  In our
  1133.             example the  company name  could be  used as a key. Each key
  1134.             would point  to one  or more records found in the data file.
  1135.             When many keys are grouped together they form an index file.
  1136.             dBASE uses  a technique called ISAM to access the underlying
  1137.             B-tree structure of its index files.
  1138.  
  1139.  
  1140.             ISAM and B-trees
  1141.  
  1142.             The relationship  between a  key and  the data  file  record
  1143.             number is  established via  a "key item". Many key items are
  1144.             found on  an "index  page". Many index pages are combined to
  1145.             form an  "index file".  The method  used to navigate through
  1146.             the index  file is called "Indexed Sequential Access Method"
  1147.             or ISAM. B-tree (or branch tree) is the underlying structure
  1148.             used in  ISAM. Searching  always begins  at the  top of  the
  1149.             tree. Each  key item  on an  index page can point to another
  1150.             index page  (this is where the "branching" comes into play).
  1151.             If a  key item  does not  point to  another index page it is
  1152.             referred to  as a  "terminal node". A search is ended when a
  1153.             terminal node is encountered.
  1154.  
  1155.  
  1156.             When a  data record for a specific key needs to be accessed,
  1157.             the first  (top) index page is searched with the desired key
  1158.             text. If  not at  a terminal  node, a  determination will be
  1159.             made using  the branch  trees as  to which index page should
  1160.             next be  searched. This  sequence of searching and branching
  1161.             is followed  until a  terminal node  is encountered.  If  an
  1162.             exact match  is found the data record number present in that
  1163.             key item can be used to access the data file.
  1164.  
  1165.  
  1166.             When a  key needs  to be  added to  an index file, the above
  1167.             sequence of  searching and branching is again followed until
  1168.             the location  where the  new key  should be placed is found.
  1169.             Because of the nature of the ISAM file it is much easier and
  1170.             faster to  add a  key to the index page than appearances may
  1171.             indicate. If  an index  page overflows it will be split into
  1172.             two pages.  Likewise if it underflows it will be joined with
  1173.             another index  page. This system results in a minimal amount
  1174.             of file I/O.
  1175.  
  1176.  
  1177.             The first  question above  has been  obviously answered, but
  1178.             what about  the second?  The answer  lies in  the fact  that
  1179.             because we are using an index file we no longer have to keep
  1180.  
  1181.  
  1182.  
  1183.                                          11
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.                            CHAPTER 3, A DATABASE TUTORIAL
  1193.  
  1194.  
  1195.             the data  file in  alphabetical order,  all we need to do is
  1196.             append records  to the end of the data file and add a key to
  1197.             the index file.
  1198.  
  1199.  
  1200.             This ends  the general discussion of databases. One note, it
  1201.             is good  programming practice to create keys only from  data
  1202.             fields  found   in  the   data  record,   this  allows   the
  1203.             reconstruction   of   an   index   file   should   something
  1204.             catastrophic happen.
  1205.  
  1206.  
  1207.             Basic Rules
  1208.  
  1209.             In order  to benefit  fully from the SoftC Database Library,
  1210.             it is  necessary to  use only  the functions  found  in  the
  1211.             library  when   performing  database   I/O.  When   standard
  1212.             functions such  as fprintf  are  used,  the  SoftC  Database
  1213.             Library file  manager is bypassed. This means that it can no
  1214.             longer keep  track of  the activities  in your  dBASE  files
  1215.             which can lead to unpredictable results.
  1216.  
  1217.  
  1218.             This is  not to  say that you cannot use the standard C file
  1219.             I/O functions  found in your compiler's libraries, but their
  1220.             use should be restricted to non-database I/O.
  1221.  
  1222.  
  1223.             Data File Functions
  1224.  
  1225.             In order  to use  a data  file  it  first  must  be  opened.
  1226.             scddopen will  open  any  dBASEIII,  dBASEIII+,  or  dBASEIV
  1227.             compatible  data  file.  The  SoftC  Database  Library  file
  1228.             manager handle  will be returned. This handle number must be
  1229.             used for all I/O with that specific data file.
  1230.  
  1231.  
  1232.             When you  are finished  with a data file it is good practice
  1233.             to close  that data  file via  a call  to scddclose. This is
  1234.             true for  a couple  of reasons:  1) the data will be safe if
  1235.             your application  crashes, and  2) computer  memory will  be
  1236.             freed for  other use. A safety net is provided by scdterm in
  1237.             that it  will close  all data, memo, and index files open at
  1238.             program termination.
  1239.  
  1240.  
  1241.             The length  of the  data file  in bytes  can be  found using
  1242.             scddsize. The  name of  the  data  file  associated  with  a
  1243.             particular handle  can be  retrieved via a call to scddinfo.
  1244.             Also a new data file can be created by scddcreate.
  1245.  
  1246.  
  1247.  
  1248.  
  1249.                                          12
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.                            CHAPTER 3, A DATABASE TUTORIAL
  1259.  
  1260.  
  1261.             Data Record I/O
  1262.  
  1263.             Having  a  data  file  is  of  little  use  unless  you  can
  1264.             manipulate the  individual  records.  The  library  provides
  1265.             seven   functions   to:   read/write   individual   records,
  1266.             delete/recover deleted  records, manipulate I/O buffers, and
  1267.             retrieve information about the record structure.
  1268.  
  1269.  
  1270.             A data  record can be read from the data file using scdrget.
  1271.             The actual  data will  be placed  in an internal buffer. See
  1272.             the discussion  on Data  Field I/O  for more  information on
  1273.             accessing the individual fields found in a data record. When
  1274.             a data  record needs  to be  written to  the  file,  scdrput
  1275.             should be  used. This function is used both for the changing
  1276.             of a record as well as adding new records.
  1277.  
  1278.  
  1279.             dBASE data  records are not physically removed from the data
  1280.             file when  they are deleted. This enables the user to change
  1281.             his mind  and recover the deleted records for use again. The
  1282.             SoftC Database  Library follows  this guideline by providing
  1283.             the scdrdel  function to  mark a data record as deleted, and
  1284.             the scdrundel  function to  recover the  record (or  mark as
  1285.             active).
  1286.  
  1287.  
  1288.             Information about the data record structure can be retrieved
  1289.             by a  call to  scdrinfo. The record length, number of fields
  1290.             in the  data record,  and the  addresses of the internal I/O
  1291.             buffers can be obtained in this way.
  1292.  
  1293.  
  1294.             Two additional functions are provided which deal exclusively
  1295.             with the  internal I/O  buffers:  scdrclear,  and  scdrcopy.
  1296.             scdrclear is  useful in  clearing the  output buffer  before
  1297.             placing data  in the  individual  fields.  The  entire  data
  1298.             record will  be set  to spaces (" "). This has the effect on
  1299.             numeric fields  of placing  nothing in the field rather than
  1300.             zero. scdrcopy  can be  useful when  a record  needs  to  be
  1301.             updated but the original also needs to be retained.
  1302.  
  1303.  
  1304.             Data Field I/O
  1305.  
  1306.             The ten  data field  manipulation functions provide for: the
  1307.             writing and  reading of  data to  and  from  fields  in  the
  1308.             internal I/O  buffer, the conversion of field names to field
  1309.             numbers,  and   the  retrieval  of  the  field  descriptions
  1310.             originally setup with scddcreate.
  1311.  
  1312.  
  1313.  
  1314.  
  1315.                                          13
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.                            CHAPTER 3, A DATABASE TUTORIAL
  1325.  
  1326.  
  1327.             There are  two types  of field  I/O: standard  C  types  and
  1328.             ASCIIZ string.  scdfput and scdfget use the standard C types
  1329.             below to  place data  in and  retrieve data  from individual
  1330.             fields in  a record. scdfput attempts to properly format the
  1331.             data before  placing it  in the  field. This  means that the
  1332.             proper number  of spaces, zeros, and/or a decimal point will
  1333.             be added as appropriate.
  1334.  
  1335.  
  1336.             C types                  dBASE types
  1337.             ASCIIZ string            character
  1338.             ASCIIZ string            date
  1339.             double                   dBASEIV BCD
  1340.             char                     logical
  1341.             unsigned long            memo
  1342.             double                   numeric
  1343.  
  1344.  
  1345.             scdfputs and  scdfgets use ASCIIZ strings exclusively. It is
  1346.             left up  to the  users of these functions to ensure that the
  1347.             data is  properly formatted.  Both "scdfput"  functions work
  1348.             with the internal output buffer, and the "scdfget" functions
  1349.             work  with   the  internal  input  buffer.  There  are  also
  1350.             "extended"  versions   of  the   preceding  four   functions
  1351.             (scdfgetx, scdfgetsx, scdfputx, scdfputx respectively) which
  1352.             allow the user to access either of the internal I/O buffers.
  1353.  
  1354.  
  1355.             A function  exists to retrieve the field descriptions (name,
  1356.             type, length,  number of  decimal places)  and the length of
  1357.             the longest  data field  (scdfinfo). A  field name  to field
  1358.             number translation  function  (scdfnam2no)  is  provided  to
  1359.             isolate your  application from  the structure  of  the  data
  1360.             files.
  1361.  
  1362.  
  1363.             Memo File Functions
  1364.  
  1365.             dBASE stores  the memo  file record number in the data file.
  1366.             The "scdfget"  functions return  the record  number and  the
  1367.             "scdfput" functions expect a valid memo record number.
  1368.  
  1369.  
  1370.             Memo files  are not automatically opened when the data files
  1371.             are opened.  These  files  must  be  explicitly  opened  via
  1372.             scdtopen. Any  dBASEIII+ compatible  memo file can be opened
  1373.             with this  function. The SoftC Database Library file manager
  1374.             handle will  be returned on exit. This handle number must be
  1375.             used for all I/O with that memo file.
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.                                          14
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                            CHAPTER 3, A DATABASE TUTORIAL
  1391.  
  1392.  
  1393.             When you  are finished  with a memo file it should be closed
  1394.             with a  call  to  scdtclose.  The  name  of  the  memo  file
  1395.             associated with  a particular  handle can be retrieved via a
  1396.             call to scdtinfo. A new file can be created by scdtcreate.
  1397.  
  1398.  
  1399.             dBASEIII inserts  soft carriage  returns in the memo data as
  1400.             it is written to the file. scdfgett will return the contents
  1401.             of the  memo record  with the soft carriage returns removed.
  1402.             scdfgettx is  an extended  function which allows the user to
  1403.             specify  whether  or  not  the  soft  carriage  returns  are
  1404.             removed.
  1405.  
  1406.  
  1407.             Two memo  record output  functions exist:  1) scdfputt  will
  1408.             automatically add  soft carriage  returns limiting memo line
  1409.             length to the value found in sc_softlen, 2) scdfputtx allows
  1410.             the user to specify whether or not soft carriage returns are
  1411.             added and,  if added,  the line  length. Note  that the memo
  1412.             file record number returned by these two functions should be
  1413.             written into  the  appropriate  data  file  field  by  using
  1414.             scdfput.
  1415.  
  1416.  
  1417.             Index File Functions
  1418.  
  1419.             In order  to use  an index  file it  first must  be  opened.
  1420.             scdnopen will  open  any  dBASEIII,  dBASEIII+,  or  dBASEIV
  1421.             compatible index  file (.NDX).  The .NTX index files created
  1422.             by Clipper  and the .MDX index files created by dBASE IV are
  1423.             not  compatible   with  dBASE  III  (and  thusly  with  this
  1424.             library). The  SoftC Database  Library file  manager  handle
  1425.             will be  returned. This  handle number  must be used for all
  1426.             I/O with that specific index file.
  1427.  
  1428.  
  1429.             When you  are finished  with an index file, it can be closed
  1430.             via a  call to  scdnclose. Information  about the index file
  1431.             such as  the file  name and length of the key expression can
  1432.             be retrieved  by a call to scdninfo. A new index file can be
  1433.             created by using the function scdncreate.
  1434.  
  1435.  
  1436.             scdnexpr can be used to get the actual index key expression.
  1437.             This key expression is generally a formula listing the field
  1438.             names used  to make  the index  key. For example, FIRST_NAME
  1439.             and LAST_NAME  are both  fields found  in a data file, if an
  1440.             index key  was made from the combination of these fields the
  1441.             key expression could be "LAST_NAME + FIRST_NAME".
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.                                          15
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.                            CHAPTER 3, A DATABASE TUTORIAL
  1457.  
  1458.  
  1459.             Index Page Functions
  1460.  
  1461.             If memory  is available  the  SoftC  Database  Library  file
  1462.             manager will  allocate space  for ten index pages. To change
  1463.             the number  of pages for which memory was allocated, scdpnum
  1464.             can be used. scdpinfo is used to find out how many pages for
  1465.             which space was allocated.
  1466.  
  1467.  
  1468.             Index Key Functions
  1469.  
  1470.             Twelve functions  have been  provided for  use in: finding a
  1471.             key, moving  to the  next or previous key, adding/deleting a
  1472.             key, retrieving  the current  key, and building a key. There
  1473.             are three  search functions  supported: find  the first  key
  1474.             (scdkfirst), finding  the last key (scdklast), and searching
  1475.             for a specific key (scdkfind). The keys found in this manner
  1476.             become the  "current key".  Wildcards such  as "?"  and  "*"
  1477.             cannot be used.
  1478.  
  1479.  
  1480.             Once a  particular key  is found  it is often desired to get
  1481.             the key following (scdknext) or the key preceding (scdkprev)
  1482.             it. These  keys, if  found, become  the current key. Another
  1483.             function is provided to return the current key, scdkcur.
  1484.  
  1485.  
  1486.             It is  also desirable to be able to add and delete keys from
  1487.             the index file. scdkadd and scdkdel provide these functions.
  1488.             These functions also attempt to keep the B-tree balanced, so
  1489.             that one  branch of  the tree  will not grow larger than the
  1490.             others.
  1491.  
  1492.  
  1493.             Two functions  are supplied  to convert date fields to valid
  1494.             index keys:  1) scdkdate  converts ASCIIZ  date  strings  of
  1495.             "mm/dd/yy", and  2) scdkdatex allows the user to specify the
  1496.             date   string    format   ("mm/dd/yy",    "mm/dd/yyyy",   or
  1497.             "yyyymmdd").
  1498.  
  1499.  
  1500.             dBASE provides  certain functions which may be used in a key
  1501.             expression. scdkmake  will build  a key  for you  using  the
  1502.             index  key  expression  and  the  current  contents  of  the
  1503.             internal output  buffer. This  function supports five of the
  1504.             more common  dBASE functions:  dtoc, left,  right, str,  and
  1505.             substr (and  the various legitimate combinations). Note that
  1506.             this function is not necessary for single field character or
  1507.             numeric keys,  but it  (or scdkdate)  can be  used for  date
  1508.             keys. scdkmakex is an extended form which allows the user to
  1509.             select which I/O buffer to use when building a key.
  1510.  
  1511.  
  1512.  
  1513.                                          16
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.           
  1523.  
  1524.  
  1525.             Chapter 4
  1526.  
  1527.  
  1528.             Clock & Calendar Functions
  1529.  
  1530.  
  1531.  
  1532.  
  1533.             This chapter  will describe  the  time  and  date  functions
  1534.             available in the SoftC Database Library. Currently there are
  1535.             seventeen functions   implemented:  thirteen  calendar,  and
  1536.             four clock.  Note that the date format is "yyyymmdd" and the
  1537.             time format is "hh:mm:ss" for all functions unless otherwise
  1538.             specified.
  1539.  
  1540.  
  1541.             Date String to String Conversion
  1542.  
  1543.             Internal  to   dBASE  the   date  fields  are  formatted  as
  1544.             "yyyymmdd". This  format enables  the date  field to be used
  1545.             properly as an index key and ensures that the date "February
  1546.             13, 1989"  will always be larger than the date "December 15,
  1547.             1988". Note  that this  date format  is not the one normally
  1548.             used when  entering or  displaying dates. If fact dBASE uses
  1549.             the date format "mm/dd/yy" when it displays dates.
  1550.  
  1551.  
  1552.             A function  sccdxlat was  created to allow switching between
  1553.             these two  formats. An  additional  format  is  provided  to
  1554.             enable the  year section  of the  date  to  more  accurately
  1555.             represent the year entered. This format is "mm/dd/yyyy".
  1556.  
  1557.  
  1558.             Date String to Numeric Conversion
  1559.  
  1560.             Along with  ASCIIZ string  dates, the  library supports  two
  1561.             types of  numeric dates:  year, month,  and day  in  integer
  1562.             form, and  number of  elapsed days  in  long  integer  form.
  1563.             sccds2n  is  used  to  convert  from  an  ASCIIZ  string  to
  1564.             integers, and  sccds2l will  convert from  ASCIIZ string  to
  1565.             long integer.
  1566.  
  1567.  
  1568.             Date Numeric to String Conversion
  1569.  
  1570.             The library  also supports the conversion to ASCIIZ strings,
  1571.             where sccdn2s  converts integers  to a  string  and  sccdl2s
  1572.             converts  a   long  integer  to  a  string.  Two  additional
  1573.             functions are  included to  return  ASCIIZ  strings  for  an
  1574.             integer day  (sccday) or month (sccmonth) input, for example
  1575.             "Thursday", or "March".
  1576.  
  1577.  
  1578.  
  1579.                                          17
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.                        CHAPTER 4, CLOCK & CALENDAR FUNCTIONS
  1589.  
  1590.  
  1591.             Date String Calculations
  1592.  
  1593.             Three functions  are provided  to perform date calculations:
  1594.             sccddiff will  compute the  difference in  days between  two
  1595.             dates, sccdperm  and sccdpermi  return the  number  of  days
  1596.             found in the month of the desired year. sccdperm requires an
  1597.             ASCIIZ string  and sccdpermi  requires an  integer year  and
  1598.             month as input.
  1599.  
  1600.  
  1601.             Date Validation and Testing
  1602.  
  1603.             Two functions  are provided  to  test  for  leap  year:  one
  1604.             requires a ASCIIZ string as input (sccleap) and the other an
  1605.             integer (sccleapi).  Also sccdvalid can be used to check the
  1606.             validity of an ASCIIZ date string.
  1607.  
  1608.  
  1609.             Time String to Numeric Conversion
  1610.  
  1611.             sccts2n can  be used  to convert  an ASCIIZ  string to three
  1612.             integers (hours, minutes, and seconds).
  1613.  
  1614.  
  1615.             Time Numeric to String Conversion
  1616.  
  1617.             A function  is also  provided to convert from integers to an
  1618.             ASCIIZ string: scctn2s.
  1619.  
  1620.  
  1621.             Time String Calculations
  1622.  
  1623.             scctdiff can be used to calculate the difference between two
  1624.             ASCIIZ time  strings. The  difference in seconds is returned
  1625.             in a long integer.
  1626.  
  1627.  
  1628.             Time Validation
  1629.  
  1630.             A function  is included in the library to validate an ASCIIZ
  1631.             time character string: scctvalid.
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.                                          18
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.           
  1655.  
  1656.  
  1657.             Chapter 5
  1658.  
  1659.  
  1660.             Miscellaneous Functions
  1661.  
  1662.  
  1663.  
  1664.  
  1665.             This chapter will describe the miscellaneous functions found
  1666.             in the SoftC Database Library.
  1667.  
  1668.  
  1669.             Program Initialization
  1670.  
  1671.             scdinit sets  up the  SoftC Database  Library file  manager.
  1672.             Memory  will   be  allocated   for  a  variety  of  internal
  1673.             structures. As  previously mentioned this function should be
  1674.             called only once at the beginning of your application.
  1675.  
  1676.  
  1677.             Program Termination
  1678.  
  1679.             scdterm is  called at  the end  of your application. It will
  1680.             close all  dBASE files  and free  the  memory  allocated  by
  1681.             scdinit.
  1682.  
  1683.  
  1684.             Library Version
  1685.  
  1686.             The scdvers function has been provided to retrieve an ASCIIZ
  1687.             string containing  the version of the SoftC Database Library
  1688.             you are currently using. This can then be printed by puts.
  1689.  
  1690.  
  1691.             Errors and Warnings
  1692.  
  1693.             A global  variable sc_code  will contain  the results of the
  1694.             last library function call executed. Errors are indicated by
  1695.             negative numbers,  warnings by positive numbers greater than
  1696.             zero, and  a zero  indicates success.  Most functions in the
  1697.             library will  NOT execute  if  sc_code  contains  an  error.
  1698.             Because  the   functions  will   not   operate   on   errant
  1699.             information,  this  feature  provides  a  small  measure  of
  1700.             security for your data.
  1701.  
  1702.  
  1703.             During program  debug it  may be  advantageous to  print the
  1704.             text message associated with the contents of sc_code. scemsg
  1705.             will return  the address  of the message associated with the
  1706.             contents of sc_code, which can then be printed by puts.
  1707.  
  1708.  
  1709.  
  1710.  
  1711.                                          19
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.                          CHAPTER 5, MISCELLANEOUS FUNCTIONS
  1721.  
  1722.  
  1723.             If you  desire to clear an error or warning condition either
  1724.             the   global variable  sc_code can  be set  to zero  or  the
  1725.             function sceclr  can be  used. It  is preferable  to use the
  1726.             function rather than the global variable.
  1727.  
  1728.  
  1729.             See Appendix  A for  a complete  list of  error and  warning
  1730.             codes and their associated messages.
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.                                          20
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.           
  1787.  
  1788.  
  1789.             Chapter 6
  1790.  
  1791.  
  1792.             The SoftC Database Library
  1793.  
  1794.  
  1795.  
  1796.  
  1797.             This chapter  contains a detailed description of each of the
  1798.             functions in the library.
  1799.  
  1800.  
  1801.             The following  sample function  description explains  how to
  1802.             use this  portion of  the SoftC  Database Library  Reference
  1803.             Manual.
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.                                          21
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  1853.  
  1854.  
  1855.             function name  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.             USAGE
  1861.                       function(
  1862.                            modifier parameter[,...]);
  1863.  
  1864.  
  1865.                       The declaration  syntax for  function, "parameter"
  1866.                       names are  underlined. The  [,...] indicates  that
  1867.                       other parameters and their modifiers may follow.
  1868.  
  1869.  
  1870.             PROTOTYPE IN
  1871.                       This lists  the header files in which the function
  1872.                       is prototyped.
  1873.  
  1874.  
  1875.             DESCRIPTION
  1876.                       This  describes   what  the   function  does,  the
  1877.                       parameters it  takes, and  any details you need in
  1878.                       order to  use function  and the  related  routines
  1879.                       listed.
  1880.  
  1881.  
  1882.             SEE ALSO
  1883.                       Routines related  to the  function about which you
  1884.                       may wish to read are listed here.
  1885.  
  1886.  
  1887.             RETURN VALUE
  1888.                       The value(s)  that the  function returns  (if any)
  1889.                       are listed here. The return value will also be set
  1890.                       in sc_code.  A good return will always be equal to
  1891.                       zero (unless  otherwise indicated  in the function
  1892.                       description).  Error   returns  are  indicated  by
  1893.                       negative numbers.  Any warning  codes  are  always
  1894.                       greater than zero.
  1895.  
  1896.  
  1897.             EXAMPLE
  1898.                       A sample  program listing  demonstrating  how  the
  1899.                       function is used.
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.                                          22
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  1919.  
  1920.  
  1921.             
  1922.             sccday    
  1923.  
  1924.  
  1925.  
  1926.  
  1927.             USAGE
  1928.                       signed int sccday(
  1929.                            signed char daystr[10],
  1930.                            signed char day );
  1931.  
  1932.  
  1933.             PROTOTYPE IN
  1934.                       sc_base.h
  1935.  
  1936.  
  1937.             DESCRIPTION
  1938.                       sccday returns  the day  of the week ASCIIZ string
  1939.                       in "daystr"  for the day specified by "day". "day"
  1940.                       must  be   in  the   range  of  0  (Sunday)  to  6
  1941.                       (Saturday).  The  maximum  length  of  the  string
  1942.                       returned will be 9 plus the NULL byte.
  1943.  
  1944.  
  1945.             SEE ALSO
  1946.                       sccmonth.
  1947.  
  1948.  
  1949.             RETURN VALUE
  1950.                       SC_SUCCESS     function successful
  1951.                       SC_BADDATE     invalid date
  1952.                       SC_NULLPARM    parameter address null
  1953.  
  1954.  
  1955.             EXAMPLE
  1956.  
  1957.             #include "sc_base.h"
  1958.             
  1959.             void main()
  1960.             {
  1961.               char day[10];
  1962.             
  1963.               scdinit(1);
  1964.               sccday(day,0);
  1965.               puts(day);
  1966.               scdterm();
  1967.             }
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.                                          23
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  1985.  
  1986.  
  1987.             
  1988.  
  1989.  
  1990.  
  1991.  
  1992.  
  1993.             sccddiff  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.             USAGE
  1999.                       signed int sccddiff(
  2000.                            signed long *diff,
  2001.                            signed char *date1,
  2002.                            signed char *date2 );
  2003.  
  2004.  
  2005.             PROTOTYPE IN
  2006.                       sc_base.h
  2007.  
  2008.  
  2009.             DESCRIPTION
  2010.                       sccddiff returns  the difference  in days  between
  2011.                       "date1" and  "date2". The  two ASCIIZ date strings
  2012.                       can be  in any  order, but must be valid  dates of
  2013.                       the format "yyyymmdd" (eg "19890213"). This is the
  2014.                       date format  used internally  by the  library file
  2015.                       manager. sccdxlat  can be  used  to  translate  an
  2016.                       existing date  string to  this format,  or a  date
  2017.                       string can be built using sccdn2s.
  2018.  
  2019.  
  2020.             SEE ALSO
  2021.                       sccdxlat, sccdn2s, sccdvalid.
  2022.  
  2023.  
  2024.             RETURN VALUE
  2025.                       SC_SUCCESS     calculation successful
  2026.                       SC_BADDATE     invalid date
  2027.                       SC_NULLPARM    parameter address null
  2028.  
  2029.  
  2030.             EXAMPLE
  2031.  
  2032.             #include "sc_base.h"
  2033.             
  2034.             void main()
  2035.             {
  2036.               signed long d;
  2037.             
  2038.  
  2039.  
  2040.  
  2041.                                          24
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2051.  
  2052.  
  2053.               scdinit(1);
  2054.               sccddiff(&d,"19890213","19881217");
  2055.               printf("%ld",d);
  2056.               scdterm();
  2057.             }
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.                                          25
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2117.  
  2118.  
  2119.             
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.             sccdl2s   
  2126.  
  2127.  
  2128.  
  2129.  
  2130.             USAGE
  2131.                       signed int sccdl2s(
  2132.                            signed char *string,
  2133.                            signed long date);
  2134.  
  2135.  
  2136.             PROTOTYPE IN
  2137.                       sc_base.h
  2138.  
  2139.  
  2140.             DESCRIPTION
  2141.                       sccdl2s converts  a long  "date"   into an  ASCIIZ
  2142.                       string "string"  of the format "yyyymmdd". A check
  2143.                       is made  to verify  that "string"  is a valid date
  2144.                       string before exiting.
  2145.  
  2146.  
  2147.             SEE ALSO
  2148.                       sccds2l.
  2149.  
  2150.  
  2151.             RETURN VALUE
  2152.                       SC_SUCCESS     conversion successful
  2153.                       SC_BADDATE     invalid date
  2154.                       SC_NULLPARM    parameter address null
  2155.  
  2156.  
  2157.             EXAMPLE
  2158.  
  2159.             #include "sc_base.h"
  2160.             
  2161.             void main()
  2162.             {
  2163.               signed char d[9];
  2164.             
  2165.               scdinit(1);
  2166.               sccdl2s(d,726489);
  2167.               puts(d);
  2168.               scdterm();
  2169.             }
  2170.  
  2171.  
  2172.  
  2173.                                          26
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2183.  
  2184.  
  2185.             
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.             sccdn2s   
  2192.  
  2193.  
  2194.  
  2195.  
  2196.             USAGE
  2197.                       signed int sccdn2s(
  2198.                            signed char *string,
  2199.                            signed int year,
  2200.                            signed int month,
  2201.                            signed int day );
  2202.  
  2203.  
  2204.             PROTOTYPE IN
  2205.                       sc_base.h
  2206.  
  2207.  
  2208.             DESCRIPTION
  2209.                       sccdn2s  converts   three  integer   date   values
  2210.                       ("year","month", and  "day") into an ASCIIZ string
  2211.                       "string" of the format "yyyymmdd". A check is made
  2212.                       to verify  that "string"  is a  valid date  string
  2213.                       before exiting.
  2214.  
  2215.  
  2216.             SEE ALSO
  2217.                       sccdvalid, sccds2n.
  2218.  
  2219.  
  2220.             RETURN VALUE
  2221.                       SC_SUCCESS     conversion successful
  2222.                       SC_BADDATE     invalid date
  2223.                       SC_NULLPARM    parameter address null
  2224.  
  2225.  
  2226.             EXAMPLE
  2227.  
  2228.             #include "sc_base.h"
  2229.             
  2230.             void main()
  2231.             {
  2232.               signed char d[9];
  2233.             
  2234.               scdinit(1);
  2235.               sccdn2s(d,1989,2,13);
  2236.  
  2237.  
  2238.  
  2239.                                          27
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2249.  
  2250.  
  2251.               puts(d);
  2252.               scdterm();
  2253.             }
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.                                          28
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2315.  
  2316.  
  2317.             
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.             sccdperm  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.             USAGE
  2329.                       signed int sccdperm(
  2330.                            signed int *days,
  2331.                            signed char *date);
  2332.  
  2333.  
  2334.             PROTOTYPE IN
  2335.                       sc_base.h
  2336.  
  2337.  
  2338.             DESCRIPTION
  2339.                       sccdperm calculates  the number  of "days"  in the
  2340.                       month for  the year  specified in "date". The date
  2341.                       must be  of the  format "yyyymmdd".  This function
  2342.                       also senses  leap year and will properly return 29
  2343.                       days for February.
  2344.  
  2345.  
  2346.             SEE ALSO
  2347.                       sccdpermi.
  2348.  
  2349.  
  2350.             RETURN VALUE
  2351.                       SC_SUCCESS     conversion successful
  2352.                       SC_BADDATE     invalid date
  2353.                       SC_NULLPARM    parameter address null
  2354.  
  2355.  
  2356.             EXAMPLE
  2357.  
  2358.             #include "sc_base.h"
  2359.             
  2360.             void main()
  2361.             {
  2362.               signed char d;
  2363.             
  2364.               scdinit(1);
  2365.               sccdperm(&d,"19890325");
  2366.               printf("%d",d);
  2367.               scdterm();
  2368.  
  2369.  
  2370.  
  2371.                                          29
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2381.  
  2382.  
  2383.             }
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.                                          30
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2447.  
  2448.  
  2449.             
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.             sccdpermi 
  2456.  
  2457.  
  2458.  
  2459.  
  2460.             USAGE
  2461.                       signed int sccdpermi(
  2462.                            signed int *days,
  2463.                            signed int year,
  2464.                            signed int month );
  2465.  
  2466.  
  2467.             PROTOTYPE IN
  2468.                       sc_base.h
  2469.  
  2470.  
  2471.             DESCRIPTION
  2472.                       sccdpermi  calculates  the  number  of  "days"  in
  2473.                       "month" for "year". This function also senses leap
  2474.                       year  and   will  properly   return  29  days  for
  2475.                       February.
  2476.  
  2477.  
  2478.             SEE ALSO
  2479.                       sccdperm.
  2480.  
  2481.  
  2482.             RETURN VALUE
  2483.                       SC_SUCCESS     conversion successful
  2484.                       SC_BADDATE     invalid date
  2485.                       SC_NULLPARM    parameter address null
  2486.  
  2487.  
  2488.             EXAMPLE
  2489.  
  2490.             #include "sc_base.h"
  2491.             
  2492.             void main()
  2493.             {
  2494.               signed char d;
  2495.             
  2496.               scdinit(1);
  2497.               sccdpermi(&d,1989,3);
  2498.               printf("%d",d);
  2499.               scdterm();
  2500.  
  2501.  
  2502.  
  2503.                                          31
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2513.  
  2514.  
  2515.             }
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.  
  2531.  
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.                                          32
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2579.  
  2580.  
  2581.             
  2582.  
  2583.  
  2584.  
  2585.  
  2586.  
  2587.             sccds2l   
  2588.  
  2589.  
  2590.  
  2591.  
  2592.             USAGE
  2593.                       signed int sccds2l(
  2594.                            signed long *date,
  2595.                            signed char *string );
  2596.  
  2597.  
  2598.             PROTOTYPE IN
  2599.                       sc_base.h
  2600.  
  2601.  
  2602.             DESCRIPTION
  2603.                       sccds2l converts  an ASCIIZ  "string" into  a long
  2604.                       "date". The  date string  must be  of  the  format
  2605.                       "yyyymmdd". This  date is  a calculated  count  of
  2606.                       days since 1/1/0000. No attempt was made to adjust
  2607.                       for changes made in the calendar. This function is
  2608.                       used   predominantly    for    date    arithmetic,
  2609.                       calculating elapsed days, etc.
  2610.  
  2611.  
  2612.             RETURN VALUE
  2613.                       SC_SUCCESS     conversion successful
  2614.                       SC_BADDATE     invalid date
  2615.                       SC_NULLPARM    parameter address null
  2616.  
  2617.  
  2618.             EXAMPLE
  2619.  
  2620.             #include "sc_base.h"
  2621.             
  2622.             void main()
  2623.             {
  2624.               signed long l;
  2625.             
  2626.               scdinit(1);
  2627.               sccds2l(&l,"19890323");
  2628.               printf("%ld",l);
  2629.               scdterm();
  2630.             }
  2631.  
  2632.  
  2633.  
  2634.  
  2635.                                          33
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2645.  
  2646.  
  2647.             
  2648.  
  2649.  
  2650.  
  2651.  
  2652.  
  2653.             sccds2n   
  2654.  
  2655.  
  2656.  
  2657.  
  2658.             USAGE
  2659.                       signed int sccds2n(
  2660.                            signed int *year,
  2661.                            signed int *month,
  2662.                            signed int *day,
  2663.                            signed char *string );
  2664.  
  2665.  
  2666.             PROTOTYPE IN
  2667.                       sc_base.h
  2668.  
  2669.  
  2670.             DESCRIPTION
  2671.                       sccds2n  converts  dates  from  an  ASCIIZ  string
  2672.                       "string" of the format "yyyymmdd" to three integer
  2673.                       values ("year",  "month", and  "day").  A  partial
  2674.                       check is  made to  verify that "string" is a valid
  2675.                       date string before attempting to convert.
  2676.  
  2677.  
  2678.             SEE ALSO
  2679.                       sccdn2s.
  2680.  
  2681.  
  2682.             RETURN VALUE
  2683.                       SC_SUCCESS     conversion successful
  2684.                       SC_BADDATE     invalid date
  2685.                       SC_NULLPARM    parameter address null
  2686.  
  2687.  
  2688.             EXAMPLE
  2689.  
  2690.             #include "sc_base.h"
  2691.             
  2692.             void main()
  2693.             {
  2694.               signed int y, m, d;
  2695.             
  2696.               scdinit(1);
  2697.               sccds2n(&y,&m,&d,"19890213");
  2698.  
  2699.  
  2700.  
  2701.                                          34
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2711.  
  2712.  
  2713.               printf("%d %d %d",y,m,d);
  2714.               scdterm();
  2715.             }
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.                                          35
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2777.  
  2778.  
  2779.             
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.             sccdvalid 
  2786.  
  2787.  
  2788.  
  2789.  
  2790.             USAGE
  2791.                       signed int sccdvalid(
  2792.                            signed char *string );
  2793.  
  2794.  
  2795.             PROTOTYPE IN
  2796.                       sc_base.h
  2797.  
  2798.  
  2799.             DESCRIPTION
  2800.                       sccdvalid tests  the date  ASCIIZ "string"  passed
  2801.                       for   validity:    string    properly    formatted
  2802.                       ("yyyymmdd"), valid  day of  month, valid month of
  2803.                       year.
  2804.  
  2805.  
  2806.             RETURN VALUE
  2807.                       SC_SUCCESS     valid date
  2808.                       SC_BADDATE     invalid date
  2809.                       SC_NULLPARM    parameter address null
  2810.  
  2811.  
  2812.             EXAMPLE
  2813.  
  2814.             #include "sc_base.h"
  2815.             
  2816.             void main()
  2817.             {
  2818.               scdinit(1);
  2819.               if (sccdvalid("19890213") == SC_SUCCESS)
  2820.                 puts("Good Date.");
  2821.               else
  2822.                 puts("Bad Date.");
  2823.               scdterm();
  2824.             }
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.                                          36
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2843.  
  2844.  
  2845.             
  2846.  
  2847.  
  2848.  
  2849.  
  2850.  
  2851.             sccdxlat  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.             USAGE
  2857.                       signed int sccdxlat(
  2858.                            signed char *dest,
  2859.                            signed char *source,
  2860.                            signed char method );
  2861.  
  2862.  
  2863.             PROTOTYPE IN
  2864.                       sc_base.h
  2865.  
  2866.  
  2867.             DESCRIPTION
  2868.                       sccdxlat translates  from one  date ASCIIZ  string
  2869.                       format  to  another  under  control  of  "method".
  2870.                       Currently three translation methods are supported:
  2871.  
  2872.  
  2873.                       SC_2ASCII      from "yyyymmdd" to "mm/dd/yy"
  2874.  
  2875.                       SC_2ASCIIL     from "yyyymmdd" to "mm/dd/yyyy"
  2876.  
  2877.                       SC_2DBASE      from "mm/dd/[yy]yy" to "yyyymmdd".
  2878.  
  2879.                       The maximum  lengths of "dest" and "source" are 10
  2880.                       characters (plus the NULL byte).
  2881.  
  2882.  
  2883.                       Note that  when converting  using SC_2DBASE  dates
  2884.                       such as "2/1/89" will be translated to "19890201".
  2885.  
  2886.  
  2887.             RETURN VALUE
  2888.                       SC_SUCCESS     translation successful
  2889.                       SC_BADCMD invalid translation method
  2890.                       SC_BADDATE     invalid date
  2891.                       SC_NULLPARM    parameter address null
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.                                          37
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2909.  
  2910.  
  2911.             EXAMPLE
  2912.  
  2913.             #include "sc_base.h"
  2914.             
  2915.             void main()
  2916.             {
  2917.               char date[11];
  2918.             
  2919.               scdinit(1);
  2920.               sccdxlat(date,"2/1/89",SC_2ASCII);
  2921.               puts(date);
  2922.               scdterm();
  2923.             }
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.                                          38
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  2975.  
  2976.  
  2977.             
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.             sccleap   
  2984.  
  2985.  
  2986.  
  2987.  
  2988.             USAGE
  2989.                       signed int sccleap(
  2990.                            signed char *leap );
  2991.  
  2992.  
  2993.             PROTOTYPE IN
  2994.                       sc_base.h
  2995.  
  2996.  
  2997.             DESCRIPTION
  2998.                       sccleap tests  the ASCIIZ year string formatted as
  2999.                       "yyyymmdd" passed  to it in "leap" to see if it is
  3000.                       a leap year.
  3001.  
  3002.  
  3003.             SEE ALSO
  3004.                       sccleapi
  3005.  
  3006.  
  3007.             RETURN VALUE
  3008.                       > 0  year was a leap year
  3009.                       SC_SUCCESS     year was not a leap year
  3010.                       SC_BADDATE     invalid date
  3011.                       SC_NULLPARM    parameter address null
  3012.  
  3013.  
  3014.             EXAMPLE
  3015.  
  3016.             #include "sc_base.h"
  3017.             
  3018.             void main()
  3019.             {
  3020.               scdinit(1);
  3021.               if (sccleap("1989")
  3022.                 puts("Leap Year!");
  3023.               else
  3024.                 puts("Normal Year.");
  3025.               scdterm();
  3026.             }
  3027.  
  3028.  
  3029.  
  3030.  
  3031.                                          39
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3041.  
  3042.  
  3043.             
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.             sccleapi  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.             USAGE
  3055.                       signed int sccleapi(
  3056.                            signed int leap );
  3057.  
  3058.  
  3059.             PROTOTYPE IN
  3060.                       sc_base.h
  3061.  
  3062.  
  3063.             DESCRIPTION
  3064.                       sccleapi tests  the integer  year passed  to it in
  3065.                       "leap" to see if it is a leap year.
  3066.  
  3067.  
  3068.             SEE ALSO
  3069.                       sccleap
  3070.  
  3071.  
  3072.             RETURN VALUE
  3073.                       > 0  year was a leap year
  3074.                       SC_SUCCESS     year was not a leap year
  3075.                       SC_BADDATE     invalid date
  3076.                       SC_NULLPARM    parameter address null
  3077.  
  3078.  
  3079.             EXAMPLE
  3080.  
  3081.             #include "sc_base.h"
  3082.             
  3083.             void main()
  3084.             {
  3085.               scdinit(1);
  3086.               if (sccleap(1989)
  3087.                 puts("Leap Year!");
  3088.               else
  3089.                 puts("Normal Year.");
  3090.               scdterm();
  3091.             }
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.                                          40
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3107.  
  3108.  
  3109.             
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.             sccmonth  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.             USAGE
  3121.                       signed int sccmonth(
  3122.                            signed char monthstr[10],
  3123.                            signed char month );
  3124.  
  3125.  
  3126.             PROTOTYPE IN
  3127.                       sc_base.h
  3128.  
  3129.  
  3130.             DESCRIPTION
  3131.                       sccmonth  returns   the  ASCIIZ  month  string  in
  3132.                       "monthstr" for  the month  specified  by  "month".
  3133.                       "month" must  be in the range of 1 (January) to 12
  3134.                       (December).  The  maximum  length  of  the  string
  3135.                       returned will be 9 plus the NULL byte.
  3136.  
  3137.  
  3138.             SEE ALSO
  3139.                       sccday
  3140.  
  3141.  
  3142.             RETURN VALUE
  3143.                       SC_SUCCESS     function successful
  3144.                       SC_BADDATE     invalid date
  3145.                       SC_NULLPARM    parameter address null
  3146.  
  3147.  
  3148.             EXAMPLE
  3149.  
  3150.             #include "sc_base.h"
  3151.             
  3152.             void main()
  3153.             {
  3154.               char month[10];
  3155.             
  3156.               scdinit(1);
  3157.               sccmonth(month,4);
  3158.               puts(month);
  3159.               scdterm();
  3160.  
  3161.  
  3162.  
  3163.                                          41
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3173.  
  3174.  
  3175.             }
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.                                          42
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3239.  
  3240.  
  3241.             
  3242.  
  3243.  
  3244.  
  3245.  
  3246.  
  3247.             scctdiff  
  3248.  
  3249.  
  3250.  
  3251.  
  3252.             USAGE
  3253.                       signed int scctdiff(
  3254.                            signed long *diff,
  3255.                            signed char *time1,
  3256.                            signed char *time2 );
  3257.  
  3258.  
  3259.             PROTOTYPE IN
  3260.                       sc_base.h
  3261.  
  3262.  
  3263.             DESCRIPTION
  3264.                       scctdiff returns the difference in seconds between
  3265.                       "time1" and  "time2". The  two ASCIIZ time strings
  3266.                       can be  in any  order, but must be valid  times of
  3267.                       the format  "hh:mm:ss"  (eg  "12:03:59").  A  time
  3268.                       string can be built using scctn2s.
  3269.  
  3270.  
  3271.             SEE ALSO
  3272.                       scctn2s, scctvalid.
  3273.  
  3274.  
  3275.             RETURN VALUE
  3276.                       SC_SUCCESS     calculation successful
  3277.                       SC_BADTIME     invalid time
  3278.                       SC_NULLPARM    parameter address null
  3279.  
  3280.  
  3281.             EXAMPLE
  3282.  
  3283.             #include "sc_base.h"
  3284.             
  3285.             void main()
  3286.             {
  3287.               signed int d;
  3288.             
  3289.               scdinit(1);
  3290.               scctdiff(&d,"12:03:59","11:30:00");
  3291.               printf("%ld",d);
  3292.  
  3293.  
  3294.  
  3295.                                          43
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3305.  
  3306.  
  3307.               scdterm();
  3308.             }
  3309.  
  3310.  
  3311.  
  3312.  
  3313.  
  3314.  
  3315.  
  3316.  
  3317.  
  3318.  
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.  
  3325.  
  3326.  
  3327.  
  3328.  
  3329.  
  3330.  
  3331.  
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.                                          44
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3371.  
  3372.  
  3373.             
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.             scctn2s   
  3380.  
  3381.  
  3382.  
  3383.  
  3384.             USAGE
  3385.                       signed int scctn2s(
  3386.                            signed char *string,
  3387.                            signed int hour,
  3388.                            signed int minute,
  3389.                            signed int second );
  3390.  
  3391.  
  3392.             PROTOTYPE IN
  3393.                       sc_base.h
  3394.  
  3395.  
  3396.             DESCRIPTION
  3397.                       scctn2s converts three integer time values "hour",
  3398.                       "minute",  and  "second"  into  an  ASCIIZ  string
  3399.                       "string" of  format "hh:mm:ss". A check is made to
  3400.                       verify that "string" is a valid time string before
  3401.                       exiting.
  3402.  
  3403.  
  3404.             SEE ALSO
  3405.                       scctvalid, sccts2n.
  3406.  
  3407.  
  3408.             RETURN VALUE
  3409.                       SC_SUCCESS     conversion successful
  3410.                       SC_BADTIME     invalid time
  3411.                       SC_NULLPARM    parameter address null
  3412.  
  3413.  
  3414.             EXAMPLE
  3415.  
  3416.             #include "sc_base.h"
  3417.             
  3418.             void main()
  3419.             {
  3420.               signed char d[9];
  3421.             
  3422.               scdinit(1);
  3423.               scctn2s(d,12,3,59);
  3424.  
  3425.  
  3426.  
  3427.                                          45
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3437.  
  3438.  
  3439.               puts(d);
  3440.               scdterm();
  3441.             }
  3442.  
  3443.  
  3444.  
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.                                          46
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3503.  
  3504.  
  3505.             
  3506.  
  3507.  
  3508.  
  3509.  
  3510.  
  3511.             sccts2n   
  3512.  
  3513.  
  3514.  
  3515.  
  3516.             USAGE
  3517.                       signed int sccts2n(
  3518.                            signed int *hour,
  3519.                            signed int *minute,
  3520.                            signed int *second,
  3521.                            signed char *string );
  3522.  
  3523.  
  3524.             PROTOTYPE IN
  3525.                       sc_base.h
  3526.  
  3527.  
  3528.             DESCRIPTION
  3529.                       sccts2n  converts  times  from  an  ASCIIZ  string
  3530.                       "string" of  format "hh:mm:ss"  to  three  integer
  3531.                       values "hour",  "minute", and  "second". A partial
  3532.                       check is  made to  verify that "string" is a valid
  3533.                       time string before attempting to convert.
  3534.  
  3535.  
  3536.             SEE ALSO
  3537.                       scctn2s.
  3538.  
  3539.  
  3540.             RETURN VALUE
  3541.                       SC_SUCCESS     conversion successful
  3542.                       SC_BADTIME     invalid time
  3543.                       SC_NULLPARM    parameter address null
  3544.  
  3545.  
  3546.             EXAMPLE
  3547.  
  3548.             #include "sc_base.h"
  3549.             
  3550.             void main()
  3551.             {
  3552.               signed int h, m, s;
  3553.             
  3554.               scdinit(1);
  3555.               sccts2n(&h,&m,&s,"12:03:59");
  3556.  
  3557.  
  3558.  
  3559.                                          47
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3569.  
  3570.  
  3571.               printf("%d %d %d",h,m,s);
  3572.               scdterm();
  3573.             }
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.                                          48
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3635.  
  3636.  
  3637.             
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.             scctvalid 
  3644.  
  3645.  
  3646.  
  3647.  
  3648.             USAGE
  3649.                       signed int scctvalid(
  3650.                            signed char *string );
  3651.  
  3652.  
  3653.             PROTOTYPE IN
  3654.                       sc_base.h
  3655.  
  3656.  
  3657.             DESCRIPTION
  3658.                       scctvalid tests  the ASCIIZ  time string  "string"
  3659.                       passed for  validity:  string  properly  formatted
  3660.                       ("hh:mm:ss"), valid hour, minute, and second.
  3661.  
  3662.  
  3663.             RETURN VALUE
  3664.                       SC_SUCCESS     valid time
  3665.                       SC_BADTIME     invalid time
  3666.                       SC_NULLPARM    parameter address null
  3667.  
  3668.  
  3669.             EXAMPLE
  3670.  
  3671.             #include "sc_base.h"
  3672.             
  3673.             void main()
  3674.             {
  3675.               scdinit(1);
  3676.               if (scctvalid("12:03:59") == SC_SUCCESS)
  3677.                 puts("Good Time.");
  3678.               else
  3679.                 puts("Bad Time.");
  3680.               scdterm();
  3681.             }
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.                                          49
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3701.  
  3702.  
  3703.             
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.             scddclose 
  3710.  
  3711.  
  3712.  
  3713.  
  3714.             USAGE
  3715.                       signed int scddclose(
  3716.                            signed char handle );
  3717.  
  3718.  
  3719.             PROTOTYPE IN
  3720.                       sc_base.h
  3721.  
  3722.  
  3723.             DESCRIPTION
  3724.                       scddclose  closes   a  data  file  and  frees  all
  3725.                       allocated  memory   associated  with   data   file
  3726.                       "handle". If  the data  file was modified, today's
  3727.                       date will be written into the file header.
  3728.  
  3729.  
  3730.             SEE ALSO
  3731.                       scddopen
  3732.  
  3733.  
  3734.             RETURN VALUE
  3735.                       SC_SUCCESS     data file closed
  3736.                       SC_CLOSFAIL    file close failure
  3737.                       SC_BADHNDL     data file not open or bad handle
  3738.                       SC_SKFAIL file seek failure
  3739.                       SC_WRTFAIL     file header write failure
  3740.  
  3741.  
  3742.             EXAMPLE
  3743.  
  3744.             #include "sc_base.h"
  3745.             
  3746.             void main()
  3747.             {
  3748.               char dbf;
  3749.             
  3750.               scdinit(15);
  3751.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS)
  3752.                 scddclose(dbf);
  3753.               scdterm();
  3754.  
  3755.  
  3756.  
  3757.                                          50
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3767.  
  3768.  
  3769.             }
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.  
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.  
  3783.  
  3784.  
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.                                          51
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3833.  
  3834.  
  3835.             
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.             scddcreate     
  3842.  
  3843.  
  3844.  
  3845.  
  3846.             USAGE
  3847.                       signed int scddcreate(
  3848.                            signed char *filename,
  3849.                            signed char numfields,
  3850.                            SC_FIELD fields[]);
  3851.  
  3852.  
  3853.             PROTOTYPE IN
  3854.                       sc_base.h
  3855.  
  3856.  
  3857.             DESCRIPTION
  3858.                       scddcreate  creates  a  dBASEIII  compatible  data
  3859.                       file. A  pointer to  an array  of SC_FIELD must be
  3860.                       passed.
  3861.  
  3862.  
  3863.                       typedef struct {
  3864.                         signed char name[11];  /* field name */
  3865.                         signed char type; /* field type */
  3866.                         unsigned char len;     /* field length */
  3867.                         unsigned char decpl;   /* decimal places */
  3868.                       } SC_FIELD;
  3869.  
  3870.  
  3871.                       The field  description array  must be  initialized
  3872.                       and each  element set  to appropriate  values. The
  3873.                       array determines  the  organization  of  the  data
  3874.                       record. The  data file  does not  remain open upon
  3875.                       exit of this function.
  3876.  
  3877.  
  3878.                       This function  will create a new data file even if
  3879.                       one had already existed.
  3880.  
  3881.  
  3882.                       Field names  and types  are converted to all upper
  3883.                       case when the file is created.
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.                                          52
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3899.  
  3900.  
  3901.                       Valid field types are:
  3902.  
  3903.  
  3904.                       'C' character (not NULL terminated in record)
  3905.                       'D' date ("yyyymmdd" format)
  3906.                       'L' logical (TRUE, FALSE)
  3907.                       'M' memo (memo file record number)
  3908.                       'N' numeric.
  3909.  
  3910.                       Restrictions:
  3911.                       The maximum record length is 4000 bytes.
  3912.                       The maximum number of fields is 128.
  3913.                       The maximum length of character fields is 254, and
  3914.                       they cannot be longer than 100 if used as a key.
  3915.                       The maximum length of numeric fields is 19.
  3916.                       The length of a date field is forced to 8.
  3917.                       The length of a logical field is forced to 1.
  3918.                       The length of a memo field is forced to 10.
  3919.                       The number of decimal places will be forced to
  3920.                       zero for all types except NUMERIC. For NUMERIC
  3921.                       fields it must be less than ('len' - 2) and also
  3922.                       less than 16. The number of decimal places cannot
  3923.                       be less than zero.
  3924.  
  3925.  
  3926.             SEE ALSO
  3927.                       scddcreatex
  3928.  
  3929.  
  3930.             RETURN VALUE
  3931.                       SC_SUCCESS     data file created
  3932.                       SC_WRTFAIL     disk write failure
  3933.                       SC_FLDCNT user supplied field description was
  3934.                                      invalid
  3935.                       SC_BADFNAME    invalid filename
  3936.                       SC_BADFLDT     invalid field type
  3937.                       SC_BADFLDN     field name invalid
  3938.                       SC_RECLEN record length error
  3939.                       SC_FLDLEN field length error
  3940.                       SC_DECPL  decimal places parameter invalid
  3941.                       SC_NOHNDL no DOS file handles available
  3942.                       SC_NULLPARM    parameter address null
  3943.  
  3944.  
  3945.             EXAMPLE
  3946.  
  3947.             #include "sc_base.h"
  3948.             
  3949.             void main()
  3950.             {
  3951.               SC_FIELD fields[] = {
  3952.  
  3953.  
  3954.  
  3955.                                          53
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  3965.  
  3966.  
  3967.                 "character",'c',16,0,     /* character field */
  3968.                 "date",'d',8,0,      /* date field */
  3969.                 "logical",'l',1,0,        /* logical field */
  3970.                 "memo",'m',0,0,      /* memo field */
  3971.                 "numeric",'n',6,2         /* numeric field */
  3972.               };
  3973.             
  3974.               scdinit(15);
  3975.               scddcreate("TEST.DBF",5,fields);
  3976.               scdterm();
  3977.             }
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.                                          54
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4031.  
  4032.  
  4033.             
  4034.  
  4035.  
  4036.  
  4037.  
  4038.  
  4039.             scddcreatex    
  4040.  
  4041.  
  4042.  
  4043.  
  4044.             USAGE
  4045.                       signed int scddcreatex(
  4046.                            signed char *filename,
  4047.                            signed char numfields,
  4048.                            SC_FIELD fields[],
  4049.                            signed char style );
  4050.  
  4051.  
  4052.             PROTOTYPE IN
  4053.                       sc_base.h
  4054.  
  4055.  
  4056.             DESCRIPTION
  4057.                       scddcreatex  creates   a   dBASEIII   or   dBASEIV
  4058.                       compatible data  file. A  pointer to  an array  of
  4059.                       SC_FIELD must be passed.
  4060.  
  4061.  
  4062.                       typedef struct {
  4063.                         signed char name[11];  /* field name */
  4064.                         signed char type; /* field type */
  4065.                         unsigned char len;     /* field length */
  4066.                         unsigned char decpl;   /* decimal places */
  4067.                       } SC_FIELD;
  4068.  
  4069.  
  4070.                       The field  description array  must be  initialized
  4071.                       and each  element set  to appropriate  values. The
  4072.                       array determines  the  organization  of  the  data
  4073.                       record. The  data file  does not  remain open upon
  4074.                       exit of this function.
  4075.  
  4076.  
  4077.                       This function  will create a new data file even if
  4078.                       one had already existed.
  4079.  
  4080.  
  4081.                       Field names  and types  are converted to all upper
  4082.                       case when the file is created.
  4083.  
  4084.  
  4085.  
  4086.  
  4087.                                          55
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4097.  
  4098.  
  4099.                       Valid field types are:
  4100.  
  4101.  
  4102.                       'C' character (not NULL terminated in record)
  4103.                       'D' date ("yyyymmdd" format)
  4104.                       'F' floating point (valid only for dBASEIV files)
  4105.                       'L' logical (TRUE, FALSE)
  4106.                       'M' memo (memo file record number)
  4107.                       'N' numeric.
  4108.  
  4109.                       Both 'F'  and 'N' fields are handled as doubles by
  4110.                       the library.  The library  does  not  support  BCD
  4111.                       numbers.
  4112.  
  4113.  
  4114.                       The type  of data  file created  depends upon  the
  4115.                       value of  the "style" parameter: SC_DB3 - dBASEIII
  4116.                       compatible, or SC_DB4 - dBASEIV compatible.
  4117.  
  4118.  
  4119.                       Restrictions:
  4120.                       The maximum record length is 4000 bytes.
  4121.                       The maximum number of dBASE III fields is 128, but
  4122.                       the maximum number of dBASEIV fields is 255.
  4123.                       The maximum length of character fields is 254, and
  4124.                       they cannot be longer than 100 if used as a key.
  4125.                       The maximum length of dBASE III numeric fields is
  4126.                       19, but the maximum length of dBASE IV numeric &
  4127.                       float fields is 20.
  4128.                       The length of a date field is forced to 8.
  4129.                       The length of a logical field is forced to 1.
  4130.                       The length of a memo field is forced to 10.
  4131.                       The number of decimal places will be forced to
  4132.                       zero for all types except: 1) dBASE III NUMERIC -
  4133.                       it must be less than ('len' - 2) and also less
  4134.                       than 16, and 2) dBASE IV NUMERIC and FLOAT - it
  4135.                       must be less than ('len' - 2). The number of
  4136.                       decimal places cannot be less than zero.
  4137.  
  4138.  
  4139.             SEE ALSO
  4140.                       scddcreate
  4141.  
  4142.  
  4143.             RETURN VALUE
  4144.                       SC_SUCCESS     data file created
  4145.                       SC_WRTFAIL     disk write failure
  4146.                       SC_FLDCNT user supplied field description was
  4147.                                      invalid
  4148.                       SC_BADFNAME    invalid filename
  4149.                       SC_BADFLDT     invalid field type
  4150.  
  4151.  
  4152.  
  4153.                                          56
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4163.  
  4164.  
  4165.                       SC_BADFLDN     field name invalid
  4166.                       SC_RECLEN record length error
  4167.                       SC_FLDLEN field length error
  4168.                       SC_DECPL  decimal places parameter invalid
  4169.                       SC_NOHNDL no DOS file handles available
  4170.                       SC_NULLPARM    parameter address null
  4171.                       SC_DBFVERS     invalid dBASE version
  4172.  
  4173.  
  4174.             EXAMPLE
  4175.  
  4176.             #include "sc_base.h"
  4177.             
  4178.             void main()
  4179.             {
  4180.               SC_FIELD fields[] = {
  4181.                 "character",'c',16,0,     /* character field */
  4182.                 "date",'d',8,0,      /* date field */
  4183.                 "float",'f',10,3,         /* float field */
  4184.                 "logical",'l',1,0,        /* logical field */
  4185.                 "memo",'m',0,0,      /* memo field */
  4186.                 "numeric",'n',6,2         /* numeric field */
  4187.               };
  4188.             
  4189.               scdinit(15);
  4190.               scddcreatex("TEST.DBF",6,fields,SC_DB4);
  4191.               scdterm();
  4192.             }
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.                                          57
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4229.  
  4230.  
  4231.             
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.             scddinfo  
  4238.  
  4239.  
  4240.  
  4241.  
  4242.             USAGE
  4243.                       signed int scddinfo(
  4244.                            signed char handle,
  4245.                            signed char *filename,
  4246.                            SC_DBFINFO *info );
  4247.  
  4248.  
  4249.             PROTOTYPE IN
  4250.                       sc_base.h
  4251.  
  4252.  
  4253.             DESCRIPTION
  4254.                       scddinfo gets the name of the file associated with
  4255.                       "handle". It  will also  return a file information
  4256.                       structure "SC_DBFINFO".
  4257.  
  4258.  
  4259.                       typedef struct {
  4260.                         signed char style;     /* file type (dBASEIII or
  4261.                       IV) */
  4262.                         signed char memo; /* memo file used flag */
  4263.                         signed char mdx;  /* MDX file used flag */
  4264.                         signed char trans;     /* transaction in
  4265.                       progress */
  4266.                         signed char encrypt;   /* data file encrypted */
  4267.                       } SC_DBFINFO;
  4268.  
  4269.  
  4270.             SEE ALSO
  4271.                       scddopen
  4272.  
  4273.  
  4274.             RETURN VALUE
  4275.                       SC_SUCCESS     returned the file name
  4276.                       SC_BADHNDL     data file not open or bad handle
  4277.                       SC_NULLPARM    parameter address null
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.                                          58
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4295.  
  4296.  
  4297.             EXAMPLE
  4298.  
  4299.             #include <dir.h>
  4300.             #include "sc_base.h"
  4301.             
  4302.             void main()
  4303.             {
  4304.               char dbf;
  4305.               char filename[MAXPATH];
  4306.               SC_DBFINFO info;
  4307.             
  4308.               scdinit(15);
  4309.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  4310.                 scddinfo(dbf,filename,&info);
  4311.                 printf("%s\n",filename);
  4312.                 if (info.style == SC_DB3)
  4313.                   printf("dBASE III data file\n");
  4314.                 else {
  4315.                   printf("dBASE IV data file\n");
  4316.                   if (info.memo)
  4317.                     printf("memo file attached\n");
  4318.                   else
  4319.                     printf("no memo file attached\n");
  4320.                   if (info.mdx)
  4321.                     printf(".MDX file used\n")
  4322.                   else
  4323.                     printf("No .MDX file used\n");
  4324.                   if (info.trans)
  4325.                     printf("Transaction in progress\n");
  4326.                   if (info.encrypt)
  4327.                     printf("File encrypted\n");
  4328.                 }
  4329.                 scddclose(dbf);
  4330.               }
  4331.               scdterm();
  4332.             }
  4333.  
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.                                          59
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4361.  
  4362.  
  4363.             
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.             scddopen  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.             USAGE
  4375.                       signed int scddopen(
  4376.                            signed char *handle,
  4377.                            signed char *filename );
  4378.  
  4379.  
  4380.             PROTOTYPE IN
  4381.                       sc_base.h
  4382.  
  4383.  
  4384.             DESCRIPTION
  4385.                       scddopen  opens   a  data  file.  Memory  will  be
  4386.                       allocated for  a file  packet and  I/O buffers for
  4387.                       use internally  by the SoftC Database Library file
  4388.                       manager. The  data file  will be tested as much as
  4389.                       possible to  insure that  it is a legitimate dBASE
  4390.                       data file.
  4391.  
  4392.  
  4393.                       All field  names and types, and the file name will
  4394.                       be converted to upper case after the file has been
  4395.                       opened.
  4396.  
  4397.  
  4398.             SEE ALSO
  4399.                       scddopenx,scddinfo
  4400.  
  4401.  
  4402.             RETURN VALUE
  4403.                       SC_SUCCESS     file opened and memory allocated
  4404.                       SC_MEMERR memory allocation failure
  4405.                       SC_NOFILE data file not found
  4406.                       SC_RDFAIL disk read failure
  4407.                       SC_SKFAIL disk seek failure
  4408.                       SC_NOHNDL no SoftC file handles available
  4409.                       SC_BADFNAME    invalid filename
  4410.                       SC_NULLPARM    parameter address null
  4411.                       SC_DBFVERS     invalid dBASE version
  4412.                       SC_DBFHLEN     header length error
  4413.                       SC_DBFDATE     last update date in error
  4414.  
  4415.  
  4416.  
  4417.                                          60
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4427.  
  4428.  
  4429.                       SC_RECLEN record length in error
  4430.                       SC_FILENGTH    file length is incorrect
  4431.                       SC_BADFLDN     invalid data field name
  4432.                       SC_BADFLDT     invalid data field type
  4433.                       SC_MDXFLAG     invalid multiple index flag
  4434.  
  4435.  
  4436.             EXAMPLE
  4437.  
  4438.             #include "sc_base.h"
  4439.             
  4440.             void main()
  4441.             {
  4442.               char dbf;
  4443.             
  4444.               scdinit(15);
  4445.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS)
  4446.                 scddclose(dbf);
  4447.               scdterm();
  4448.             }
  4449.  
  4450.  
  4451.  
  4452.  
  4453.  
  4454.  
  4455.  
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.                                          61
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4493.  
  4494.  
  4495.             
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.             scddopenx 
  4502.  
  4503.  
  4504.  
  4505.  
  4506.             USAGE
  4507.                       signed int scddopenx(
  4508.                            signed char *handle,
  4509.                            signed char *filename,
  4510.                            SC_DBFINFO *info );
  4511.  
  4512.  
  4513.             PROTOTYPE IN
  4514.                       sc_base.h
  4515.  
  4516.  
  4517.             DESCRIPTION
  4518.                       scddopenx  opens  a  data  file.  Memory  will  be
  4519.                       allocated for  a file  packet and  I/O buffers for
  4520.                       use internally  by the SoftC Database Library file
  4521.                       manager. The  data file  will be tested as much as
  4522.                       possible to  insure that  it is a legitimate dBASE
  4523.                       data file.
  4524.  
  4525.  
  4526.                       The structure  SC_DBFINFO is  used to  return data
  4527.                       file status:
  4528.  
  4529.  
  4530.                       typedef struct {
  4531.                         signed char style;     /* file type (dBASEIII or
  4532.                       IV) */
  4533.                         signed char memo; /* memo file used flag */
  4534.                         signed char mdx;  /* MDX file used flag */
  4535.                         signed char trans;     /* transaction in
  4536.                       progress */
  4537.                         signed char encrypt;   /* data file encrypted */
  4538.                       } SC_DBFINFO;
  4539.  
  4540.  
  4541.                       All field  names and types, and the file name will
  4542.                       be converted to upper case after the file has been
  4543.                       opened.
  4544.  
  4545.  
  4546.  
  4547.  
  4548.  
  4549.                                          62
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4559.  
  4560.  
  4561.             SEE ALSO
  4562.                       scddopen
  4563.  
  4564.  
  4565.             RETURN VALUE
  4566.                       SC_SUCCESS     file opened and memory allocated
  4567.                       SC_NOFILE data file not found
  4568.                       SC_RDFAIL disk read failure
  4569.                       SC_SKFAIL disk seek failure
  4570.                       SC_BADFNAME    invalid filename
  4571.                       SC_NULLPARM    parameter address null
  4572.                       SC_DBFVERS     invalid dBASE version
  4573.                       SC_DBFHLEN     header length error
  4574.                       SC_DBFDATE     last update date in error
  4575.                       SC_RECLEN record length in error
  4576.                       SC_FILENGTH    file length is incorrect
  4577.                       SC_BADFLDN     invalid data field name
  4578.                       SC_BADFLDT     invalid data field type
  4579.                       SC_MDXFLAG     invalid multiple index flag
  4580.  
  4581.  
  4582.             EXAMPLE
  4583.  
  4584.             #include "sc_base.h"
  4585.             
  4586.             void main()
  4587.             {
  4588.               char dbf;
  4589.               SC_DBFINFO info;
  4590.             
  4591.               scdinit(15);
  4592.               if (scddopenx(&dbf,"TEST.DBF",&info) == SC_SUCCESS) {
  4593.                 printf("%s\n",filename);
  4594.                 if (info.style == SC_DB3)
  4595.                   printf("dBASE III data file\n");
  4596.                 else {
  4597.                   printf("dBASE IV data file\n");
  4598.                   if (info.memo)
  4599.                     printf("memo file attached\n");
  4600.                   else
  4601.                     printf("no memo file attached\n");
  4602.                   if (info.mdx)
  4603.                     printf(".MDX file used\n")
  4604.                   else
  4605.                     printf("No .MDX file used\n");
  4606.                   if (info.trans)
  4607.                     printf("Transaction in progress\n");
  4608.                   if (info.encrypt)
  4609.                     printf("File encrypted\n");
  4610.                 }
  4611.                 scddclose(dbf);
  4612.  
  4613.  
  4614.  
  4615.                                          63
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4625.  
  4626.  
  4627.               }
  4628.               scdterm();
  4629.             }
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.                                          64
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4691.  
  4692.  
  4693.             
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.             scddsize  
  4700.  
  4701.  
  4702.  
  4703.  
  4704.             USAGE
  4705.                       signed int scddsize(
  4706.                            signed char handle,
  4707.                            signed long *recsused );
  4708.  
  4709.  
  4710.             PROTOTYPE IN
  4711.                       sc_base.h
  4712.  
  4713.  
  4714.             DESCRIPTION
  4715.                       scddsize gets  the number of records "recsused" in
  4716.                       the  data  file.  This  number  will  include  all
  4717.                       records marked  as inactive  as well as all active
  4718.                       records.
  4719.  
  4720.  
  4721.             RETURN VALUE
  4722.                       SC_SUCCESS     returned the number of records
  4723.                       SC_BADHNDL     data file not open or bad handle
  4724.                       SC_NULLPARM    parameter address null
  4725.  
  4726.  
  4727.             EXAMPLE
  4728.  
  4729.             #include "sc_base.h"
  4730.             
  4731.             void main()
  4732.             {
  4733.               char dbf;
  4734.               long recsused;
  4735.             
  4736.               scdinit(15);
  4737.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  4738.                 scddsize(dbf,&recsused);
  4739.                 printf("%ld",recsused);
  4740.                 scddclose(dbf);
  4741.               }
  4742.               scdterm();
  4743.             }
  4744.  
  4745.  
  4746.  
  4747.                                          65
  4748.  
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4757.  
  4758.  
  4759.             
  4760.  
  4761.  
  4762.  
  4763.  
  4764.  
  4765.             scdfget   
  4766.  
  4767.  
  4768.  
  4769.  
  4770.             USAGE
  4771.                       signed int scdfget(
  4772.                            signed char handle,
  4773.                            signed char fieldno,
  4774.                            void *data );
  4775.  
  4776.  
  4777.             PROTOTYPE IN
  4778.                       sc_base.h
  4779.  
  4780.  
  4781.             DESCRIPTION
  4782.                       scdfget gets data from the desired field "fieldno"
  4783.                       of the input buffer. "data" will be converted from
  4784.                       dBASE to a more natural data type for 'c':
  4785.  
  4786.  
  4787.                       dBASE field type   returned data type
  4788.                       'C'                signed char *
  4789.                       'D'                signed char [9]
  4790.                       'F'                double (dBASEIV)
  4791.                       'L'                signed char
  4792.                       'M'                unsigned long
  4793.                       'N'                double
  4794.  
  4795.  
  4796.                       Date and  character fields  are returned as ASCIIZ
  4797.                       strings. The  date strings  will be  formatted  as
  4798.                       "mm/dd/yy".
  4799.  
  4800.  
  4801.                       Data returned  by this function for memo fields is
  4802.                       the memo  file record  number NOT  the actual memo
  4803.                       text. A  call must  be made  to either scdfgett or
  4804.                       scdfgettx to retrieve the memo text.
  4805.  
  4806.  
  4807.                       scdfinfo can  be used  to determine  the length of
  4808.                       the longest data field in the file.
  4809.  
  4810.  
  4811.  
  4812.  
  4813.                                          66
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4823.  
  4824.  
  4825.                       Note that fields are numbered from zero (0).
  4826.  
  4827.  
  4828.             SEE ALSO
  4829.                       scdfgett, scdfgettx, scdfgets, scdfgetx, scdfput,
  4830.                       scdfinfo, scdrget.
  4831.  
  4832.  
  4833.             RETURN VALUE
  4834.                       SC_SUCCESS     retrieved data from field
  4835.                       SC_BADHNDL     data file not open or bad handle
  4836.                       SC_NULLPARM    parameter address null
  4837.                       SC_FLDCNT invalid number of fields
  4838.                       SC_BADDATE     invalid date
  4839.  
  4840.  
  4841.             EXAMPLE
  4842.  
  4843.             #include "sc_base.h"
  4844.             
  4845.             void main()
  4846.             {
  4847.               char dbf, character[17],logical,date[9];
  4848.               double numeric;
  4849.               unsigned long memo;
  4850.             
  4851.               scdinit(15);
  4852.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  4853.                 scdrget(dbf,1L);
  4854.                 scdfgets(dbf,0,character);
  4855.                 scdfget(dbf,1,(void *) date);
  4856.                 scdfget(dbf,2,(void *) &logical);
  4857.                 scdfget(dbf,3,(void *) &memo);
  4858.                 scdfget(dbf,4,(void *) &numeric);
  4859.                 printf("%s %s %c %lu %lf\n",
  4860.             character,date,logical,memo,numeric);
  4861.                 scddclose(dbf);
  4862.               }
  4863.               scdterm();
  4864.             }
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.                                          67
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4889.  
  4890.  
  4891.             
  4892.  
  4893.  
  4894.  
  4895.  
  4896.  
  4897.             scdfgets  
  4898.  
  4899.  
  4900.  
  4901.  
  4902.             USAGE
  4903.                       signed int scdfgets(
  4904.                            signed char handle,
  4905.                            signed char fieldno,
  4906.                            char *data );
  4907.  
  4908.  
  4909.             PROTOTYPE IN
  4910.                       sc_base.h
  4911.  
  4912.  
  4913.             DESCRIPTION
  4914.                       scdfgets  gets   data  from   the  desired   field
  4915.                       "fieldno" of  the input  buffer.  "data"  will  be
  4916.                       returned as an ASCIIZ string.
  4917.  
  4918.  
  4919.                       scdfinfo can  be used  to determine  the length of
  4920.                       the longest data field in the file.
  4921.  
  4922.  
  4923.                       Note that  date fields  are returned  in the  form
  4924.                       "yyyymmdd". There is a difference between the date
  4925.                       formats of scdfgets and scdfget.
  4926.  
  4927.  
  4928.                       Note that fields are numbered from zero (0).
  4929.  
  4930.  
  4931.             SEE ALSO
  4932.                       scdfget, scdfgetsx, scdfputs, scdfinfo, scdrget.
  4933.  
  4934.  
  4935.             RETURN VALUE
  4936.                       SC_SUCCESS     retrieved data from field
  4937.                       SC_BADHNDL     data file not open or bad handle
  4938.                       SC_NULLPARM    parameter address null
  4939.                       SC_FLDCNT invalid number of fields
  4940.                       SC_BADDATE     invalid date
  4941.  
  4942.  
  4943.  
  4944.  
  4945.                                          68
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  4955.  
  4956.  
  4957.             EXAMPLE
  4958.  
  4959.             #include "sc_base.h"
  4960.             
  4961.             void main()
  4962.             {
  4963.               char dbf, character[17], logical, date[9];
  4964.               double numeric;
  4965.               unsigned long
  4966.             
  4967.               scdinit(15);
  4968.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  4969.                 scdrget(dbf,1L);
  4970.                 scdfgets(dbf,0,character);
  4971.                 scdfgets(dbf,1,date);
  4972.                 scdfget(dbf,2,(void *) &logical);
  4973.                 scdfget(dbf,3,(void *) &memo);
  4974.                 scdfget(dbf,4,(void *) &numeric);
  4975.                 printf("%s %s %c %lu %lf\n",
  4976.             character,date,logical,memo,numeric);
  4977.                 scddclose(dbf);
  4978.               }
  4979.               scdterm();
  4980.             }
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.                                          69
  5012.  
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5021.  
  5022.  
  5023.             
  5024.  
  5025.  
  5026.  
  5027.  
  5028.  
  5029.             scdfgetsx 
  5030.  
  5031.  
  5032.  
  5033.  
  5034.             USAGE
  5035.                       signed int scdfgetsx(
  5036.                            signed char handle,
  5037.                            signed char fieldno,
  5038.                            char *data,
  5039.                            signed int buffer );
  5040.  
  5041.  
  5042.             PROTOTYPE IN
  5043.                       sc_base.h
  5044.  
  5045.  
  5046.             DESCRIPTION
  5047.                       scdfgetsx is an extended version of scdfgets which
  5048.                       extracts data  from the desired field "fieldno" of
  5049.                       the I/O buffer specified by "buffer". Use SC_INPUT
  5050.                       for the  input buffer and SC_OUTPUT for the output
  5051.                       buffer. "data"  will  be  returned  as  an  ASCIIZ
  5052.                       string.
  5053.  
  5054.  
  5055.                       scdfinfo can  be used  to determine  the length of
  5056.                       the longest data field in the file.
  5057.  
  5058.  
  5059.                       Note that  date fields  are returned  in the  form
  5060.                       "yyyymmdd". There is a difference between the date
  5061.                       formats of scdfgetsx and scdfgetx.
  5062.  
  5063.  
  5064.                       Note that fields are numbered from zero (0).
  5065.  
  5066.  
  5067.             SEE ALSO
  5068.                       scdfgets, scdfgetx, scdfputs, scdfinfo, scdrget.
  5069.  
  5070.  
  5071.             RETURN VALUE
  5072.                       SC_SUCCESS     retrieved data from field
  5073.                       SC_BADHNDL     data file not open or bad handle
  5074.  
  5075.  
  5076.  
  5077.                                          70
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5087.  
  5088.  
  5089.                       SC_NULLPARM    parameter address null
  5090.                       SC_FLDCNT invalid number of fields
  5091.                       SC_BADDATE     invalid date
  5092.                       SC_BADCMD invalid I/O buffer selection
  5093.  
  5094.  
  5095.             EXAMPLE
  5096.  
  5097.             #include "sc_base.h"
  5098.             
  5099.             void main()
  5100.             {
  5101.               char dbf, character[17], logical, date[9];
  5102.               double numeric;
  5103.               unsigned long memo;
  5104.             
  5105.               scdinit(15);
  5106.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  5107.                 scdrget(dbf,1L);
  5108.                 scdfgetsx(dbf,0,character,SC_INPUT);
  5109.                 scdfgetsx(dbf,1,date,SC_INPUT);
  5110.                 scdfgetx(dbf,2,(void *) &logical,SC_INPUT);
  5111.                 scdfgetx(dbf,3,(void *) &memo,SC_INPUT);
  5112.                 scdfgetx(dbf,4,(void *) &numeric,SC_INPUT);
  5113.                 printf("%s %s %c %lu %lf\n",
  5114.                   character,date,logical,memo,numeric);
  5115.                 scddclose(dbf);
  5116.               }
  5117.               scdterm();
  5118.             }
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.                                          71
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5153.  
  5154.  
  5155.             
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.             scdfgett  
  5162.  
  5163.  
  5164.  
  5165.  
  5166.             USAGE
  5167.                       signed int scdfgett(
  5168.                            signed char handle,
  5169.                            signed long recno,
  5170.                            signed char **data );
  5171.  
  5172.  
  5173.             PROTOTYPE IN
  5174.                       sc_base.h
  5175.  
  5176.  
  5177.             DESCRIPTION
  5178.                       scdfgett reads the desired record "recno" from the
  5179.                       memo file  specified by  "handle". A  buffer large
  5180.                       enough to  hold the  text will  be  allocated  the
  5181.                       address of  which is  returned in "data". The soft
  5182.                       carriage returns  embedded in  the  text  will  be
  5183.                       removed.
  5184.  
  5185.  
  5186.             SEE ALSO
  5187.                       scdfget, scdfgettx, scdfputt.
  5188.  
  5189.  
  5190.             RETURN VALUE
  5191.                       SC_SUCCESS     retrieved data from file
  5192.                       SC_BADHNDL     memo file not open or bad handle
  5193.                       SC_NULLPARM    parameter address null
  5194.                       SC_SKFAIL seek failure
  5195.                       SC_RDFAIL file read failure
  5196.                       SC_MEMERR memory allocation failure
  5197.                       SC_FLDLEN invalid field length
  5198.                       SC_FILBAD file may be corrupted
  5199.  
  5200.  
  5201.             EXAMPLE
  5202.  
  5203.             #include "sc_base.h"
  5204.             
  5205.             void main()
  5206.  
  5207.  
  5208.  
  5209.                                          72
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5219.  
  5220.  
  5221.             {
  5222.               char dbt, *data;
  5223.             
  5224.               scdinit(15);
  5225.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS) {
  5226.                 scdfgett(dbt,1L,&data);
  5227.                 puts(data);
  5228.                 scddclose(dbt);
  5229.               }
  5230.               scdterm();
  5231.             }
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.                                          73
  5276.  
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5285.  
  5286.  
  5287.             
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.             scdfgettx 
  5294.  
  5295.  
  5296.  
  5297.  
  5298.             USAGE
  5299.                       signed int scdfgettx(
  5300.                            signed char handle,
  5301.                            signed long recno,
  5302.                            signed char **data,
  5303.                            signed int command );
  5304.  
  5305.  
  5306.             PROTOTYPE IN
  5307.                       sc_base.h
  5308.  
  5309.  
  5310.             DESCRIPTION
  5311.                       scdfgettx is an extended version of scdfgett which
  5312.                       allows the user to control whether or not the soft
  5313.                       carriage returns  are stripped  via "command". Use
  5314.                       SC_CRUNCHNG to  leave the  soft  carriage  returns
  5315.                       alone, or use SC_CRDELETE to remove them.
  5316.  
  5317.  
  5318.             SEE ALSO
  5319.                       scdfgett.
  5320.  
  5321.  
  5322.             RETURN VALUE
  5323.                       SC_SUCCESS     retrieved data from file
  5324.                       SC_BADHNDL     memo file not open or bad handle
  5325.                       SC_NULLPARM    parameter address null
  5326.                       SC_SKFAIL seek failure
  5327.                       SC_RDFAIL file read failure
  5328.                       SC_MEMERR memory allocation failure
  5329.                       SC_FLDLEN invalid field length
  5330.                       SC_FILBAD file may be corrupted
  5331.                       SC_BADCMD invalid command
  5332.  
  5333.  
  5334.             EXAMPLE
  5335.  
  5336.             #include "sc_base.h"
  5337.             
  5338.  
  5339.  
  5340.  
  5341.                                          74
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5351.  
  5352.  
  5353.             void main()
  5354.             {
  5355.               char dbt, *data;
  5356.             
  5357.               scdinit(15);
  5358.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS) {
  5359.                 scdfgettx(dbt,1L,&data,SC_CRDELETE);
  5360.                 puts(data);
  5361.                 scddclose(dbt);
  5362.               }
  5363.               scdterm();
  5364.             }
  5365.  
  5366.  
  5367.  
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.                                          75
  5408.  
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5417.  
  5418.  
  5419.             
  5420.  
  5421.  
  5422.  
  5423.  
  5424.  
  5425.             scdfgetx  
  5426.  
  5427.  
  5428.  
  5429.  
  5430.             USAGE
  5431.                       signed int scdfgetx(
  5432.                            signed char handle,
  5433.                            signed char fieldno,
  5434.                            char *data,
  5435.                            signed int buffer );
  5436.  
  5437.  
  5438.             PROTOTYPE IN
  5439.                       sc_base.h
  5440.  
  5441.  
  5442.             DESCRIPTION
  5443.                       scdfgetx is  an extended  version of scdfget which
  5444.                       extracts data  from the desired field "fieldno" of
  5445.                       the I/O buffer specified by "buffer". Use SC_INPUT
  5446.                       for the  input buffer and SC_OUTPUT for the output
  5447.                       buffer.
  5448.  
  5449.  
  5450.                       dBASE field type   returned data type
  5451.                       'C'                signed char *
  5452.                       'D'                signed char [9]
  5453.                       'F'                double (dBASEIV)
  5454.                       'L'                signed char
  5455.                       'M'                unsigned long
  5456.                       'N'                double
  5457.  
  5458.  
  5459.                       Date and  character fields  are returned as ASCIIZ
  5460.                       strings. The  date strings  will be  formatted  as
  5461.                       "mm/dd/yy". There is a difference between the date
  5462.                       formats of scdfgetx and scdfgets.
  5463.  
  5464.  
  5465.                       Data returned  by this function for memo fields is
  5466.                       the memo  file record  number NOT  the actual memo
  5467.                       text. A  call must  be made  to either scdfgett or
  5468.                       scdfgettx to retrieve the memo text.
  5469.  
  5470.  
  5471.  
  5472.  
  5473.                                          76
  5474.  
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5483.  
  5484.  
  5485.                       scdfinfo can  be used  to determine  the length of
  5486.                       the longest data field in the file.
  5487.  
  5488.  
  5489.                       Note that fields are numbered from zero (0).
  5490.  
  5491.  
  5492.             SEE ALSO
  5493.                       scdfget, scdfgetsx, scdfput, scdfinfo, scdrget.
  5494.  
  5495.  
  5496.             RETURN VALUE
  5497.                       SC_SUCCESS     retrieved data from field
  5498.                       SC_BADHNDL     data file not open or bad handle
  5499.                       SC_NULLPARM    parameter address null
  5500.                       SC_FLDCNT invalid number of fields
  5501.                       SC_BADDATE     invalid date
  5502.                       SC_BADCMD invalid I/O buffer selection
  5503.  
  5504.  
  5505.             EXAMPLE
  5506.  
  5507.             #include "sc_base.h"
  5508.             
  5509.             void main()
  5510.             {
  5511.               char dbf, character[17], logical, date[9];
  5512.               double numeric;
  5513.               unsigned long memo;
  5514.             
  5515.               scdinit(15);
  5516.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  5517.                 scdrget(dbf,1L);
  5518.                 scdfgetsx(dbf,0,character,SC_INPUT);
  5519.                 scdfgetsx(dbf,1,date,SC_INPUT);
  5520.                 scdfgetx(dbf,2,(void *) &logical,SC_INPUT);
  5521.                 scdfgetx(dbf,3,(void *) &memo,SC_INPUT);
  5522.                 scdfgetx(dbf,4,(void *) &numeric,SC_INPUT);
  5523.                 printf("%s %s %c %lu %lf\n",
  5524.             character,date,logical,memo,numeric);
  5525.                 scddclose(dbf);
  5526.               }
  5527.               scdterm();
  5528.             }
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.                                          77
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5549.  
  5550.  
  5551.             
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.             scdfinfo  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.             USAGE
  5563.                       signed int scdfinfo(
  5564.                            signed char handle,
  5565.                            signed char *longfldlen,
  5566.                            SC_FIELD *fields );
  5567.  
  5568.  
  5569.             PROTOTYPE IN
  5570.                       sc_base.h
  5571.  
  5572.  
  5573.             DESCRIPTION
  5574.                       scdfinfo copies  the data  field  descriptions  to
  5575.                       "fields" using  the structure SC_FIELD. The length
  5576.                       of  the   longest  data  field  is  also  returned
  5577.                       "longfldlen".
  5578.  
  5579.  
  5580.                       typedef struct {
  5581.                         signed char name[11];  /* field name */
  5582.                         signed char type; /* field type */
  5583.                         unsigned char len;     /* field length */
  5584.                         unsigned char decpl;   /* decimal places */
  5585.                       } SC_FIELD;
  5586.  
  5587.  
  5588.                       The user  must ensure  that the  array defined for
  5589.                       "fields" is  large enough to hold all of the field
  5590.                       descriptions because  scdfinfo blindly  copies the
  5591.                       descriptions to  "fields". Severe  program  errors
  5592.                       can be the result if the field array is too small.
  5593.                       Use scdrinfo  to determine the number of fields in
  5594.                       the data record.
  5595.  
  5596.  
  5597.             SEE ALSO
  5598.                       scdrinfo
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.                                          78
  5606.  
  5607.  
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5615.  
  5616.  
  5617.             RETURN VALUE
  5618.                       SC_SUCCESS     returned the field descriptions
  5619.                       SC_BADHNDL     data file not open or bad handle
  5620.                       SC_NULLPARM    parameter address null
  5621.  
  5622.  
  5623.             EXAMPLE
  5624.  
  5625.             #include "sc_base.h"
  5626.             
  5627.             void main()
  5628.             {
  5629.               char dbf, longfld, numflds, a;
  5630.               SC_FIELD fields[128];  /* dBASEIII max size */
  5631.               short reclen;
  5632.               void *ibfr, *obfr;
  5633.             
  5634.               scdinit(15);
  5635.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  5636.                 scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr);
  5637.                 scdfinfo(dbf,&longfld,fields);
  5638.                 printf("longest field length = %d\n",longfld);
  5639.                 for (a = 0; a < numflds; a++)
  5640.                   printf("%s %c %d %d\n", fields[a].name,
  5641.             fields[a].type,
  5642.                       fields[a].len, fields[a].decpl);
  5643.                 scddclose(dbf);
  5644.               }
  5645.               scdterm();
  5646.             }
  5647.  
  5648.  
  5649.  
  5650.  
  5651.  
  5652.  
  5653.  
  5654.  
  5655.  
  5656.  
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  
  5663.  
  5664.  
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.                                          79
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5681.  
  5682.  
  5683.             
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.             scdfnam2no     
  5690.  
  5691.  
  5692.  
  5693.  
  5694.             USAGE
  5695.                       signed int scdfnam2no(
  5696.                            signed char handle,
  5697.                            signed int *fieldno,
  5698.                            signed char *fieldname );
  5699.  
  5700.  
  5701.             PROTOTYPE IN
  5702.                       sc_base.h
  5703.  
  5704.  
  5705.             DESCRIPTION
  5706.                       scdfnam2no searches  through the field description
  5707.                       array  for   data  file   "handle"   looking   for
  5708.                       "fieldname".  It  will  return  the  corresponding
  5709.                       field number.
  5710.  
  5711.  
  5712.                       Note that data files created by the SoftC Database
  5713.                       Library will have field names and types changed to
  5714.                       all upper case.
  5715.  
  5716.  
  5717.             RETURN VALUE
  5718.                       SC_SUCCESS     field number returned
  5719.                       SC_BADHNDL     data file not open or bad handle
  5720.                       SC_BADFLDN     invalid data record field name
  5721.                       SC_NULLPARM    parameter address null
  5722.  
  5723.  
  5724.             EXAMPLE
  5725.  
  5726.             #include "sc_base.h"
  5727.             
  5728.             void main()
  5729.             {
  5730.               char dbf, fldno
  5731.             
  5732.               scdinit(15);
  5733.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  5734.  
  5735.  
  5736.  
  5737.                                          80
  5738.  
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5747.  
  5748.  
  5749.                 scdfnam2no(dbf,&fldno,"LOGICAL");
  5750.                 printf("%d",fldno);
  5751.                 scddclose(dbf);
  5752.               }
  5753.               scdterm();
  5754.             }
  5755.  
  5756.  
  5757.  
  5758.  
  5759.  
  5760.  
  5761.  
  5762.  
  5763.  
  5764.  
  5765.  
  5766.  
  5767.  
  5768.  
  5769.  
  5770.  
  5771.  
  5772.  
  5773.  
  5774.  
  5775.  
  5776.  
  5777.  
  5778.  
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.                                          81
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5813.  
  5814.  
  5815.             
  5816.  
  5817.  
  5818.  
  5819.  
  5820.  
  5821.             scdfput   
  5822.  
  5823.  
  5824.  
  5825.  
  5826.             USAGE
  5827.                       signed int scdfput(
  5828.                            signed char handle,
  5829.                            signed char fieldno,
  5830.                            void *data );
  5831.  
  5832.  
  5833.             PROTOTYPE IN
  5834.                       sc_base.h
  5835.  
  5836.  
  5837.             DESCRIPTION
  5838.                       scdfput will  convert "data"  from 'c'  format  to
  5839.                       dBASE format  and place  it in  the  proper  field
  5840.                       "fieldno" of the output buffer.
  5841.  
  5842.  
  5843.                       dBASE field type   returned data type
  5844.                       'C'                signed char *
  5845.                       'D'                signed char [9]
  5846.                       'L'                signed char
  5847.                       'M'                unsigned long
  5848.                       'N'                double
  5849.  
  5850.  
  5851.                       Note that fields are numbered from zero (0).
  5852.  
  5853.  
  5854.                       Note that  scdfput  follows  the  date  formatting
  5855.                       standard of scdfget. It is optional to include the
  5856.                       "19" from  "1989" as  this is assumed, however the
  5857.                       date "2/1/00"  will become  "19000201" even if you
  5858.                       had intended it to be "20000201". Date strings can
  5859.                       be  formatted   as  "2/1/2000"  to  overcome  this
  5860.                       problem.
  5861.  
  5862.  
  5863.             SEE ALSO
  5864.                       scdfget, scdfputs, scdfputx.
  5865.  
  5866.  
  5867.  
  5868.  
  5869.                                          82
  5870.  
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5879.  
  5880.  
  5881.             RETURN VALUE
  5882.                       SC_SUCCESS     data placed in field
  5883.                       SC_BADHNDL     data file not open or bad handle
  5884.                       SC_NULLPARM    parameter address null
  5885.                       SC_BADDATE     invalid date field
  5886.                       SC_FLDTRUNC    character field truncated
  5887.                       SC_BADDATA     bad data to be written
  5888.                       SC_FLDCNT invalid field number
  5889.                       SC_FLDROUND    numeric field rounded
  5890.  
  5891.  
  5892.             EXAMPLE
  5893.  
  5894.             #include "sc_base.h"
  5895.             
  5896.             void main()
  5897.             {
  5898.               char dbf, logical = 'T', date[9] = "12/25/88";
  5899.               long recno;
  5900.               double numeric = 20.0L;
  5901.               unsigned long memo = 1L;
  5902.             
  5903.               scdinit(15);
  5904.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  5905.                 scdfputs(dbf,0,"SoftC Database Library   ");
  5906.                 scdfput(dbf,1,(void *) date);
  5907.                 scdfput(dbf,2,(void *) &logical);
  5908.                 scdfput(dbf,3,(void *) &memo)
  5909.                 scdfput(dbf,4,(void *) &numeric);
  5910.                 scdrput(dbf,&recno,SC_ADD);
  5911.                 printf("Record number = %ld\n",recno);
  5912.                 scddclose(dbf);
  5913.               }
  5914.               scdterm();
  5915.             }
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.  
  5935.                                          83
  5936.  
  5937.  
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  5945.  
  5946.  
  5947.             
  5948.  
  5949.  
  5950.  
  5951.  
  5952.  
  5953.             scdfputs  
  5954.  
  5955.  
  5956.  
  5957.  
  5958.             USAGE
  5959.                       signed int scdfputs(
  5960.                            signed char handle,
  5961.                            signed char fieldno,
  5962.                            char *data );
  5963.  
  5964.  
  5965.             PROTOTYPE IN
  5966.                       sc_base.h
  5967.  
  5968.  
  5969.             DESCRIPTION
  5970.                       scdfputs will  place "data"  in the  proper  field
  5971.                       "fieldno" of  the output  buffer. It is the user's
  5972.                       responsibility to  provide a  properly  sized  and
  5973.                       formatted ASCIIZ string to scdfputs.
  5974.  
  5975.  
  5976.                       Note that fields are numbered from zero (0).
  5977.  
  5978.  
  5979.                       Note that  scdfputs follows  the  date  formatting
  5980.                       conventions of  scdfgets. Also  be aware  that the
  5981.                       date formatting conventions of scdfget/scdfput are
  5982.                       not the same as scdfgets/scdfputs.
  5983.  
  5984.  
  5985.             SEE ALSO
  5986.                       scdfgets, scdfput, scdfputsx.
  5987.  
  5988.  
  5989.             RETURN VALUE
  5990.                       SC_SUCCESS     data placed in field
  5991.                       SC_BADHNDL     data file not open or bad handle
  5992.                       SC_NULLPARM    parameter address null
  5993.                       SC_BADDATE     invalid date field
  5994.                       SC_FLDTRUNC    character field truncated
  5995.                       SC_BADDATA     bad data to be written
  5996.                       SC_FLDCNT invalid field number
  5997.  
  5998.  
  5999.  
  6000.  
  6001.                                          84
  6002.  
  6003.  
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6011.  
  6012.  
  6013.             EXAMPLE
  6014.  
  6015.             #include "sc_base.h"
  6016.             
  6017.             void main()
  6018.             {
  6019.               char dbf, logical,date[9];
  6020.               long recno;
  6021.               double numeric;
  6022.               unsigned long memo;
  6023.             
  6024.               scdinit(15);
  6025.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  6026.                 scdfputs(dbf,0,"SoftC Database library   ");
  6027.                 scdfputs(dbf,1, date);
  6028.                 scdfput(dbf,2,(void *) &logical);
  6029.                 scdfput(dbf,3,(void *) &memo);
  6030.                 scdfput(dbf,4,(void *) &numeric);
  6031.                 scdrput(dbf,&recno,SC_ADD);
  6032.                 printf("Record number = %ld\n",recno);
  6033.                 scddclose(dbf);
  6034.               }
  6035.               scdterm();
  6036.             }
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  
  6043.  
  6044.  
  6045.  
  6046.  
  6047.  
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.                                          85
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6077.  
  6078.  
  6079.             
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.             scdfputsx 
  6086.  
  6087.  
  6088.  
  6089.  
  6090.             USAGE
  6091.                       signed int scdfputsx(
  6092.                            signed char handle,
  6093.                            signed char fieldno,
  6094.                            char *data,
  6095.                            signed int buffer );
  6096.  
  6097.  
  6098.             PROTOTYPE IN
  6099.                       sc_base.h
  6100.  
  6101.  
  6102.             DESCRIPTION
  6103.                       scdfputsx is an extended version of scdfputs which
  6104.                       allows the placement of "data" in the proper field
  6105.                       "fieldno" of the I/O buffer specified by "buffer".
  6106.                       Use SC_INPUT  for the  input buffer  and SC_OUTPUT
  6107.                       for  the   output  buffer.   It  is   the   user's
  6108.                       responsibility to  provide a  properly  sized  and
  6109.                       formatted ASCIIZ string to scdfputsx.
  6110.  
  6111.  
  6112.                       Note that fields are numbered from zero (0).
  6113.  
  6114.  
  6115.                       Note that  scdfputsx follows  the date  formatting
  6116.                       conventions of  scdfgets. Also  be aware  that the
  6117.                       date formatting conventions of scdfget/scdfput are
  6118.                       not the same as scdfgets/scdfputsx.
  6119.  
  6120.  
  6121.             SEE ALSO
  6122.                       scdfgets, scdfput, scdfputs.
  6123.  
  6124.  
  6125.             RETURN VALUE
  6126.                       SC_SUCCESS     data placed in field
  6127.                       SC_BADHNDL     data file not open or bad handle
  6128.                       SC_NULLPARM    parameter address null
  6129.                       SC_BADDATE     invalid date field
  6130.  
  6131.  
  6132.  
  6133.                                          86
  6134.  
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6143.  
  6144.  
  6145.                       SC_FLDTRUNC    character field truncated
  6146.                       SC_BADDATA     bad data to be written
  6147.                       SC_FLDCNT invalid field number
  6148.                       SC_FLDROUND    numeric field rounded
  6149.                       SC_BADCMD invalid I/O buffer selection
  6150.  
  6151.  
  6152.             EXAMPLE
  6153.  
  6154.             #include "sc_base.h"
  6155.             
  6156.             void main()
  6157.             {
  6158.               char dbf, logical,date[9];
  6159.               long recno;
  6160.               double numeric;
  6161.               unsigned long memo;
  6162.             
  6163.               scdinit(15);
  6164.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  6165.                 scdfputsx(dbf,0,"SoftC Database Library   ",SC_OUTPUT);
  6166.                 scdfputsx(dbf,1, date,SC_OUTPUT);
  6167.                 scdfputx(dbf,2,(void *) &logical,SC_OUTPUT);
  6168.                 scdfputx(dbf,3,(void *) &memo,SC_OUTPUT);
  6169.                 scdfputx(dbf,4,(void *) &numeric,SC_OUTPUT);
  6170.                 scdrput(dbf,&recno,SC_ADD);
  6171.                 printf("Record number = %ld\n",recno);
  6172.                 scddclose(dbf);
  6173.               }
  6174.               scdterm();
  6175.             }
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.  
  6196.  
  6197.  
  6198.  
  6199.                                          87
  6200.  
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6209.  
  6210.  
  6211.             
  6212.  
  6213.  
  6214.  
  6215.  
  6216.  
  6217.             scdfputt  
  6218.  
  6219.  
  6220.  
  6221.  
  6222.             USAGE
  6223.                       signed int scdfputt(
  6224.                            signed char handle,
  6225.                            signed long *recno,
  6226.                            signed char *data );
  6227.  
  6228.  
  6229.             PROTOTYPE IN
  6230.                       sc_base.h
  6231.  
  6232.  
  6233.             DESCRIPTION
  6234.                       scdfputt writes  "data" to the memo file specified
  6235.                       by "handle". The record number written is returned
  6236.                       in  "recno".  This  record  number  must  be  then
  6237.                       written to  the data  output buffer  via a call to
  6238.                       scdfput. This  function assumes  that "data" is an
  6239.                       ASCIIZ string  with a  maximum  length  of  65,536
  6240.                       characters.
  6241.  
  6242.  
  6243.                       Soft carriage  returns will be added into the memo
  6244.                       record so as to limit the line length to the value
  6245.                       contained in  sc_softlen. This  global variable is
  6246.                       initially set  to 66.  There  are  limits  to  the
  6247.                       values allowed  in sc_softlen:  it cannot  be less
  6248.                       than 10 nor greater than 132. If it is set to zero
  6249.                       (0) then no soft carriage returns will be added.
  6250.  
  6251.  
  6252.             SEE ALSO
  6253.                       scdfgett, scdfput, scdfputtx.
  6254.  
  6255.  
  6256.             RETURN VALUE
  6257.                       SC_SUCCESS     data written to file
  6258.                       SC_BADHNDL     memo file not open or bad handle
  6259.                       SC_NULLPARM    parameter address null
  6260.                       SC_SKFAIL seek failure
  6261.                       SC_LINELEN     invalid soft line length
  6262.  
  6263.  
  6264.  
  6265.                                          88
  6266.  
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6275.  
  6276.  
  6277.             EXAMPLE
  6278.  
  6279.             #include "sc_base.h"
  6280.             
  6281.             void main()
  6282.             {
  6283.               char dbt, data[512];
  6284.               long recno;
  6285.             
  6286.               scdinit(15);
  6287.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS) {
  6288.                 strcpy(data,"hello world.");
  6289.                 scdfputt(dbt,&recno,data);
  6290.                 printf("%ld",recno);
  6291.                 scddclose(dbt);
  6292.               }
  6293.               scdterm();
  6294.             }
  6295.  
  6296.  
  6297.  
  6298.  
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.                                          89
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6341.  
  6342.  
  6343.             
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.             scdfputtx 
  6350.  
  6351.  
  6352.  
  6353.  
  6354.             USAGE
  6355.                       signed int scdfputtx(
  6356.                            signed char handle,
  6357.                            signed long *recno,
  6358.                            signed char *data,
  6359.                            signed int linelength );
  6360.  
  6361.  
  6362.             PROTOTYPE IN
  6363.                       sc_base.h
  6364.  
  6365.  
  6366.             DESCRIPTION
  6367.                       scdfputtx is an extended version of scdfputt which
  6368.                       allows the user to directly control whether or not
  6369.                       the soft  carriage returns  are added  and, if so,
  6370.                       where.  If   "linelength"  is  zero  (0)  no  soft
  6371.                       carriage returns  will be added, else "linelength"
  6372.                       specifies the maximum length of a memo line.
  6373.  
  6374.  
  6375.                       Note that  existing soft  carriage returns are not
  6376.                       removed before new ones are added.
  6377.  
  6378.  
  6379.             SEE ALSO
  6380.                       scdfputt.
  6381.  
  6382.  
  6383.             RETURN VALUE
  6384.                       SC_SUCCESS     data written to file
  6385.                       SC_BADHNDL     memo file not open or bad handle
  6386.                       SC_NULLPARM    parameter address null
  6387.                       SC_SKFAIL seek failure
  6388.                       SC_LINELEN     invalid soft line length
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394.  
  6395.  
  6396.  
  6397.                                          90
  6398.  
  6399.  
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6407.  
  6408.  
  6409.             EXAMPLE
  6410.  
  6411.             #include "sc_base.h"
  6412.             
  6413.             void main()
  6414.             {
  6415.               char dbt, data[512];
  6416.               long recno;
  6417.             
  6418.               scdinit(15);
  6419.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS) {
  6420.                 strcpy(data,"hello world.");
  6421.                 scdfputtx(dbt,&recno,data,sc_softlen);
  6422.                 printf("%ld",recno);
  6423.                 scddclose(dbt);
  6424.               }
  6425.               scdterm();
  6426.             }
  6427.  
  6428.  
  6429.  
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.  
  6463.                                          91
  6464.  
  6465.  
  6466.  
  6467.  
  6468.  
  6469.  
  6470.  
  6471.  
  6472.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6473.  
  6474.  
  6475.             
  6476.  
  6477.  
  6478.  
  6479.  
  6480.  
  6481.             scdfputx  
  6482.  
  6483.  
  6484.  
  6485.  
  6486.             USAGE
  6487.                       signed int scdfputx(
  6488.                            signed char handle,
  6489.                            signed char fieldno,
  6490.                            void *data,
  6491.                            signed int buffer );
  6492.  
  6493.  
  6494.             PROTOTYPE IN
  6495.                       sc_base.h
  6496.  
  6497.  
  6498.             DESCRIPTION
  6499.                       scdfputx is  an extended  version of scdfput which
  6500.                       allows the placement of "data" in the proper field
  6501.                       "fieldno" of the I/O buffer specified by "buffer".
  6502.                       Use SC_INPUT  for the  input buffer  and SC_OUTPUT
  6503.                       for the output buffer.
  6504.  
  6505.  
  6506.                       dBASE field type:  returned data type:
  6507.                       'C'                signed char *
  6508.                       'D'                signed char [9]
  6509.                       'L'                signed char
  6510.                       'M'                unsigned long
  6511.                       'N'                double
  6512.  
  6513.  
  6514.                       Note that fields are numbered from zero (0).
  6515.  
  6516.  
  6517.                       Note that  scdfputx follows  the  date  formatting
  6518.                       standard of scdfget. It is optional to include the
  6519.                       "19" from  "1989" as  this is assumed, however the
  6520.                       date "2/1/00"  will become  "19000201" even if you
  6521.                       had intended it to be "20000201". Date strings can
  6522.                       be  formatted   as  "2/1/2000"  to  overcome  this
  6523.                       problem. Also  be aware  that the  date formatting
  6524.                       conventions of  scdfget/scdfputx are  not the same
  6525.                       as scdfgets/scdfputs.
  6526.  
  6527.  
  6528.  
  6529.                                          92
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6539.  
  6540.  
  6541.             SEE ALSO
  6542.                       scdfgets, scdfput, scdfputs.
  6543.  
  6544.  
  6545.             RETURN VALUE
  6546.                       SC_SUCCESS     data placed in field
  6547.                       SC_BADHNDL     data file not open or bad handle
  6548.                       SC_NULLPARM    parameter address null
  6549.                       SC_BADDATE     invalid date field
  6550.                       SC_FLDTRUNC    character field truncated
  6551.                       SC_BADDATA     bad data to be written
  6552.                       SC_FLDCNT invalid field number
  6553.                       SC_FLDROUND    numeric field rounded
  6554.                       SC_BADCMD invalid I/O buffer selection
  6555.  
  6556.  
  6557.             EXAMPLE
  6558.  
  6559.             #include "sc_base.h"
  6560.             
  6561.             void main()
  6562.             {
  6563.               char dbf, logical,date[9];
  6564.               long recno;
  6565.               double numeric;
  6566.               unsigned long memo;
  6567.             
  6568.               scdinit(15);
  6569.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  6570.                 scdfputsx(dbf,0,"SoftC Database Library   ",SC_OUTPUT);
  6571.                 scdfputsx(dbf,1, date,SC_OUTPUT);
  6572.                 scdfputx(dbf,2,(void *) &logical,SC_OUTPUT);
  6573.                 scdfputx(dbf,3,(void *) &memo,SC_OUTPUT);
  6574.                 scdfputx(dbf,4,(void *) &numeric,SC_OUTPUT);
  6575.                 scdrput(dbf,&recno,SC_ADD);
  6576.                 printf("Record number = %ld\n",recno);
  6577.                 scddclose(dbf);
  6578.               }
  6579.               scdterm();
  6580.             }
  6581.  
  6582.  
  6583.  
  6584.  
  6585.  
  6586.  
  6587.  
  6588.  
  6589.  
  6590.  
  6591.  
  6592.  
  6593.  
  6594.  
  6595.                                          93
  6596.  
  6597.  
  6598.  
  6599.  
  6600.  
  6601.  
  6602.  
  6603.  
  6604.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6605.  
  6606.  
  6607.             
  6608.  
  6609.  
  6610.  
  6611.  
  6612.  
  6613.             scdinit   
  6614.  
  6615.  
  6616.  
  6617.  
  6618.             USAGE
  6619.                       signed int scdinit(
  6620.                            signed char files );
  6621.  
  6622.  
  6623.             PROTOTYPE IN
  6624.                       sc_base.h
  6625.  
  6626.  
  6627.             DESCRIPTION
  6628.                       scdinit is  called  once  and  only  once  at  the
  6629.                       beginning of  the program.  The maximum  number of
  6630.                       simultaneously  open   "files"  is   passed.  This
  6631.                       function sets  up the  SoftC Database Library file
  6632.                       manager environment for processing. Memory will be
  6633.                       allocated for a variety of control structures used
  6634.                       internally by the file manager.
  6635.  
  6636.  
  6637.                       Note: DOS  defaults to  a maximum of 20 open files
  6638.                       per program.  The first  five are  taken  up  with
  6639.                       printer, console,  auxiliary  port,  etc.  leaving
  6640.                       only 15  file handles  available per  program.  So
  6641.                       passing a  value greater  than 15  in "files" will
  6642.                       only waste memory.
  6643.  
  6644.  
  6645.                       Note that  neither Microsoft C 5.1 nor Turbo C 2.0
  6646.                       support more than 20 open files.
  6647.  
  6648.  
  6649.             SEE ALSO
  6650.                       scdterm.
  6651.  
  6652.  
  6653.             RETURN VALUE
  6654.                       SC_SUCCESS     completed initialization
  6655.                       SC_MEMERR memory allocation failure
  6656.                       SC_BADHNDL     invalid number of handles
  6657.  
  6658.  
  6659.  
  6660.  
  6661.                                          94
  6662.  
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6671.  
  6672.  
  6673.             EXAMPLE
  6674.  
  6675.             #include "sc_base.h"
  6676.             
  6677.             void main()
  6678.             {
  6679.               scdinit(15);
  6680.               scdterm();
  6681.             }
  6682.  
  6683.  
  6684.  
  6685.  
  6686.  
  6687.  
  6688.  
  6689.  
  6690.  
  6691.  
  6692.  
  6693.  
  6694.  
  6695.  
  6696.  
  6697.  
  6698.  
  6699.  
  6700.  
  6701.  
  6702.  
  6703.  
  6704.  
  6705.  
  6706.  
  6707.  
  6708.  
  6709.  
  6710.  
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.  
  6725.  
  6726.  
  6727.                                          95
  6728.  
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6737.  
  6738.  
  6739.             
  6740.  
  6741.  
  6742.  
  6743.  
  6744.  
  6745.             scdkadd   
  6746.  
  6747.  
  6748.  
  6749.  
  6750.             USAGE
  6751.                       signed int scdkadd(
  6752.                            signed char handle,
  6753.                            signed char *key,
  6754.                            signed long recno );
  6755.  
  6756.  
  6757.             PROTOTYPE IN
  6758.                       sc_base.h
  6759.  
  6760.  
  6761.             DESCRIPTION
  6762.                       scdkadd will add "key" to the index file specified
  6763.                       by "handle".  "recno" is the data record number to
  6764.                       be associated  with "key" (the data record pointed
  6765.                       to by recno must exist prior to calling scdkadd).
  6766.  
  6767.  
  6768.                       Note that  when adding  character keys  it is  not
  6769.                       necessary   to   pad   the key string to size with
  6770.                       spaces ("  "), the  function will automatically do
  6771.                       this for you.
  6772.  
  6773.  
  6774.             SEE ALSO
  6775.                       scdkdate, scdkmake.
  6776.  
  6777.  
  6778.             RETURN VALUE
  6779.                       SC_SUCCESS     key added to index file
  6780.                       SC_BADHNDL     index file not open or bad handle
  6781.                       SC_SKFAIL disk seek failure
  6782.                       SC_WRTFAIL     disk write failure
  6783.                       SC_RDFAIL disk read failure
  6784.                       SC_MEMERR memory allocation failure
  6785.                       SC_NULLPARM    parameter address null
  6786.  
  6787.  
  6788.  
  6789.  
  6790.  
  6791.  
  6792.  
  6793.                                          96
  6794.  
  6795.  
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6803.  
  6804.  
  6805.             EXAMPLE
  6806.  
  6807.             #include <string.h>
  6808.             #include "sc_base.h"
  6809.             
  6810.             void main()
  6811.             {
  6812.               char dbf, ndx, date[9];
  6813.               short result;
  6814.               long recno;
  6815.             
  6816.               scdinit(15);
  6817.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  6818.                 if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  6819.                   strcpy(date,"19881201");
  6820.                   scdfputs(dbf,1,date);
  6821.                   result = scdrput(dbf,&recno,SC_ADD)
  6822.                   if (result == SC_SUCCESS)
  6823.                     scdkadd(ndx,date,recno);
  6824.                   scdnclose(ndx);
  6825.                 }
  6826.                 scddclose(dbf)
  6827.               }
  6828.               scdterm();
  6829.             }
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841.  
  6842.  
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.                                          97
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6869.  
  6870.  
  6871.             
  6872.  
  6873.  
  6874.  
  6875.  
  6876.  
  6877.             scdkcur   
  6878.  
  6879.  
  6880.  
  6881.  
  6882.             USAGE
  6883.                       signed int scdkcur(
  6884.                            signed char handle,
  6885.                            signed char *key,
  6886.                            signed long *recno );
  6887.  
  6888.  
  6889.             PROTOTYPE IN
  6890.                       sc_base.h
  6891.  
  6892.  
  6893.             DESCRIPTION
  6894.                       scdkcur will  return the  key value "key" and data
  6895.                       record number  "recno" associated with the current
  6896.                       key in the index file.
  6897.  
  6898.  
  6899.                       The current  key pointer  must be set by a call to
  6900.                       either scdkfind, scdkfirst, scdklast, scdknext, or
  6901.                       scdkprev before calling scdkcur.
  6902.  
  6903.  
  6904.                       The user  must ensure  that  the  buffer  used  to
  6905.                       return the  key is large enough to hold the entire
  6906.                       key.  The   maximum  length  of  the  key  can  be
  6907.                       determined via a call to scdninfo.
  6908.  
  6909.  
  6910.             SEE ALSO
  6911.                       scdninfo, scdkfind, scdkfirst, scdklast, scdknext,
  6912.                       scdkprev.
  6913.  
  6914.  
  6915.             RETURN VALUE
  6916.                       SC_SUCCESS     key and recno returned
  6917.                       SC_BADHNDL     index file not open or bad handle
  6918.                       SC_END    no current key
  6919.                       SC_RDFAIL read index file failure
  6920.                       SC_SKFAIL seek failure (bad record address or seek
  6921.                                      fail)
  6922.  
  6923.  
  6924.  
  6925.                                          98
  6926.  
  6927.  
  6928.  
  6929.  
  6930.  
  6931.  
  6932.  
  6933.  
  6934.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  6935.  
  6936.  
  6937.                       SC_NULLPARM    parameter address null
  6938.  
  6939.  
  6940.             EXAMPLE
  6941.  
  6942.             #include "sc_base.h"
  6943.             
  6944.             void main()
  6945.             {
  6946.               char ndx, date[9], dat[9];
  6947.               long recno, recn;
  6948.             
  6949.               scdinit(15);
  6950.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  6951.                 date[8] = 0;
  6952.                 dat[8] = 0;
  6953.                 scdkfirst(ndx,date,&recn);
  6954.                 scdkcur(ndx,dat,&recno);
  6955.                 printf("%s %s %ld %ld\n",      date,dat,recno,recn);
  6956.                 scdnclose(ndx);
  6957.               }
  6958.               scdterm();
  6959.             }
  6960.  
  6961.  
  6962.  
  6963.  
  6964.  
  6965.  
  6966.  
  6967.  
  6968.  
  6969.  
  6970.  
  6971.  
  6972.  
  6973.  
  6974.  
  6975.  
  6976.  
  6977.  
  6978.  
  6979.  
  6980.  
  6981.  
  6982.  
  6983.  
  6984.  
  6985.  
  6986.  
  6987.  
  6988.  
  6989.  
  6990.  
  6991.                                          99
  6992.  
  6993.  
  6994.  
  6995.  
  6996.  
  6997.  
  6998.  
  6999.  
  7000.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7001.  
  7002.  
  7003.             
  7004.  
  7005.  
  7006.  
  7007.  
  7008.  
  7009.             scdkdate  
  7010.  
  7011.  
  7012.  
  7013.  
  7014.             USAGE
  7015.                       signed int scdkdate(
  7016.                            double *key,
  7017.                            signed char *string );
  7018.  
  7019.  
  7020.             PROTOTYPE IN
  7021.                       sc_base.h
  7022.  
  7023.  
  7024.             DESCRIPTION
  7025.                       scdkdate will  translate  an  ASCIIZ  date  string
  7026.                       "string" of  format "yyyymmdd"  into a valid dBASE
  7027.                       date key "key".
  7028.  
  7029.  
  7030.             RETURN VALUE
  7031.                       SC_SUCCESS     index key created
  7032.                       SC_NULLPARM    parameter address null
  7033.                       SC_BADDATE     invalid date string
  7034.  
  7035.  
  7036.             EXAMPLE
  7037.  
  7038.             #include <string.h>
  7039.             #include "sc_base.h"
  7040.             
  7041.             void main()
  7042.             {
  7043.               double key;
  7044.             
  7045.               scdinit(15);
  7046.               scdkdate(&key,"19890801");
  7047.               printf("%lf",key);
  7048.               scdterm();
  7049.             }
  7050.  
  7051.  
  7052.  
  7053.  
  7054.  
  7055.  
  7056.  
  7057.                                          100
  7058.  
  7059.  
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.  
  7066.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7067.  
  7068.  
  7069.             
  7070.  
  7071.  
  7072.  
  7073.  
  7074.  
  7075.             scdkdatex 
  7076.  
  7077.  
  7078.  
  7079.  
  7080.             USAGE
  7081.                       signed int scdkdatex(
  7082.                            double *key,
  7083.                            signed char *string,
  7084.                            signed int method );
  7085.  
  7086.  
  7087.             PROTOTYPE IN
  7088.                       sc_base.h
  7089.  
  7090.  
  7091.             DESCRIPTION
  7092.                       scdkdatex is  an extended  form of  scdkdate which
  7093.                       allows the user to translate an ASCIIZ date string
  7094.                       "string"  of  either  "yyyymmdd",  "mm/dd/yy",  or
  7095.                       "mm/dd/yyyy" format  into a  valid dBASE  date key
  7096.                       "key".
  7097.  
  7098.  
  7099.                       Use "method"  of SC_DBASE  to translate "yyyymmdd"
  7100.                       strings,   and    SC_ASCII   for   "mm/dd/yy"   or
  7101.                       "mm/dd"yyyy".
  7102.  
  7103.  
  7104.             RETURN VALUE
  7105.                       SC_SUCCESS     index key created
  7106.                       SC_NULLPARM    parameter address null
  7107.                       SC_BADDATE     invalid date string
  7108.  
  7109.  
  7110.             EXAMPLE
  7111.  
  7112.             #include <string.h>
  7113.             #include "sc_base.h"
  7114.             
  7115.             void main()
  7116.             {
  7117.               double key;
  7118.             
  7119.               scdinit(15);
  7120.  
  7121.  
  7122.  
  7123.                                          101
  7124.  
  7125.  
  7126.  
  7127.  
  7128.  
  7129.  
  7130.  
  7131.  
  7132.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7133.  
  7134.  
  7135.               scdkdatex(&key,"19890801",SC_DBASE);
  7136.               printf("%lf",key);
  7137.               scdterm();
  7138.             }
  7139.  
  7140.  
  7141.  
  7142.  
  7143.  
  7144.  
  7145.  
  7146.  
  7147.  
  7148.  
  7149.  
  7150.  
  7151.  
  7152.  
  7153.  
  7154.  
  7155.  
  7156.  
  7157.  
  7158.  
  7159.  
  7160.  
  7161.  
  7162.  
  7163.  
  7164.  
  7165.  
  7166.  
  7167.  
  7168.  
  7169.  
  7170.  
  7171.  
  7172.  
  7173.  
  7174.  
  7175.  
  7176.  
  7177.  
  7178.  
  7179.  
  7180.  
  7181.  
  7182.  
  7183.  
  7184.  
  7185.  
  7186.  
  7187.  
  7188.  
  7189.                                          102
  7190.  
  7191.  
  7192.  
  7193.  
  7194.  
  7195.  
  7196.  
  7197.  
  7198.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7199.  
  7200.  
  7201.             
  7202.  
  7203.  
  7204.  
  7205.  
  7206.  
  7207.             scdkdel   
  7208.  
  7209.  
  7210.  
  7211.  
  7212.             USAGE
  7213.                       signed int scdkdel(
  7214.                            signed char handle,
  7215.                            signed char *key,
  7216.                            signed long recno );
  7217.  
  7218.  
  7219.             PROTOTYPE IN
  7220.                       sc_base.h
  7221.  
  7222.  
  7223.             DESCRIPTION
  7224.                       scdkdel will  remove "key"  from  the  index  file
  7225.                       specified by  "handle". "recno" is used along with
  7226.                       "key" to  ensure that  the  proper  key  has  been
  7227.                       removed from the index file.
  7228.  
  7229.  
  7230.                       Note that  when deleting  character keys it is not
  7231.                       necessary   to   pad   the key string to size with
  7232.                       spaces ("  "), the  function will automatically do
  7233.                       this for you.
  7234.  
  7235.  
  7236.             SEE ALSO
  7237.                       scdkadd.
  7238.  
  7239.  
  7240.             RETURN VALUE
  7241.                       SC_SUCCESS     key removed from index file
  7242.                       SC_BADHNDL     index file not open or bad handle
  7243.                       SC_SKFAIL disk seek failure
  7244.                       SC_WRTFAIL     disk write failure
  7245.                       SC_RDFAIL index file read failure
  7246.                       SC_EMPTY  index file is empty - no keys found
  7247.                       SC_NOFIND desired key was not found
  7248.                       SC_NULLPARM    parameter address null
  7249.                       SC_FILBAD index file may be corrupted
  7250.  
  7251.  
  7252.  
  7253.  
  7254.  
  7255.                                          103
  7256.  
  7257.  
  7258.  
  7259.  
  7260.  
  7261.  
  7262.  
  7263.  
  7264.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7265.  
  7266.  
  7267.             EXAMPLE
  7268.  
  7269.             #include <string.h>
  7270.             #include "sc_base.h"
  7271.             
  7272.             void main()
  7273.             {
  7274.               char ndx, date[9];
  7275.               long recno;
  7276.             
  7277.               scdinit(15);
  7278.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  7279.                 strcpy(date,"19881202");
  7280.                 recno = 7L;
  7281.                 scdkdel(ndx,date,recno);
  7282.                 scdnclose(ndx);
  7283.               }
  7284.               scdterm();
  7285.             }
  7286.  
  7287.  
  7288.  
  7289.  
  7290.  
  7291.  
  7292.  
  7293.  
  7294.  
  7295.  
  7296.  
  7297.  
  7298.  
  7299.  
  7300.  
  7301.  
  7302.  
  7303.  
  7304.  
  7305.  
  7306.  
  7307.  
  7308.  
  7309.  
  7310.  
  7311.  
  7312.  
  7313.  
  7314.  
  7315.  
  7316.  
  7317.  
  7318.  
  7319.  
  7320.  
  7321.                                          104
  7322.  
  7323.  
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7331.  
  7332.  
  7333.             
  7334.  
  7335.  
  7336.  
  7337.  
  7338.  
  7339.             scdkfind  
  7340.  
  7341.  
  7342.  
  7343.  
  7344.             USAGE
  7345.                       signed int scdkfind(
  7346.                            signed char handle,
  7347.                            signed char *key,
  7348.                            signed long *recno,
  7349.                            signed char method );
  7350.  
  7351.  
  7352.             PROTOTYPE IN
  7353.                       sc_base.h
  7354.  
  7355.  
  7356.             DESCRIPTION
  7357.                       scdkfind   supports   two   key   search   methods
  7358.                       (determined by "method"): SC_EXACT - find an exact
  7359.                       match with  "key" and "recno", and SC_FIRST - find
  7360.                       the first logical occurrence of "key" in the index
  7361.                       and return the associated record number "recno" if
  7362.                       found.
  7363.  
  7364.  
  7365.                       If a  match cannot  be found, the current key will
  7366.                       be  the   physical  key  which  would  immediately
  7367.                       precede "key".  The current  key's value  and data
  7368.                       record  number  will  be  returned  in  "key"  and
  7369.                       "recno".
  7370.  
  7371.  
  7372.                       The user  must ensure  that  the  buffer  used  to
  7373.                       return the  key is large enough to hold the entire
  7374.                       key.  The   maximum  length  of  the  key  can  be
  7375.                       determined via a call to scdninfo.
  7376.  
  7377.  
  7378.                       Note that  when searching  using character keys it
  7379.                       is not  necessary  to  pad  the key string to size
  7380.                       with spaces (" "), the function will automatically
  7381.                       do this for you.
  7382.  
  7383.  
  7384.  
  7385.  
  7386.  
  7387.                                          105
  7388.  
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7397.  
  7398.  
  7399.                       Note  that  searching  for  partial  keys  can  be
  7400.                       accomplished by  using the  SC_FIRST  method.  For
  7401.                       example, you  are using  a fifteen  character  key
  7402.                       size. You  want to  find the first entry where the
  7403.                       first five characters are "ABCDE". All you need do
  7404.                       is copy  that five  character ASCIIZ  string  into
  7405.                       your  key  buffer  and  then  call  scdkfind.  The
  7406.                       function will  space pad  to length  and then find
  7407.                       the first matching entry.
  7408.  
  7409.  
  7410.                       Note that  numeric keys  are returned  as doubles,
  7411.                       and character keys are returned as strings.
  7412.  
  7413.  
  7414.             SEE ALSO
  7415.                       scdninfo.
  7416.  
  7417.  
  7418.             RETURN VALUE
  7419.                       SC_SUCCESS     key found
  7420.                       SC_NOFIND key not found
  7421.                       SC_EMPTY  index file empty - no keys found
  7422.                       SC_BADHNDL     index file not open or bad handle
  7423.                       SC_SKFAIL seek failure (bad record address or seek
  7424.                                      fail)
  7425.                       SC_RDFAIL read index file failure
  7426.                       SC_NULLPARM    parameter address null
  7427.  
  7428.  
  7429.             EXAMPLE
  7430.  
  7431.             #include <string.h>
  7432.             #include "sc_base.h"
  7433.             
  7434.             void main()
  7435.             {
  7436.               char ndx, key[16];
  7437.               long recno;
  7438.               int result;
  7439.             
  7440.               scdinit(15);
  7441.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  7442.                 strcpy(key,"ABCDE");
  7443.                 recno = 7L;
  7444.                 if (scdkfind(ndx,key,&recno,SC_FIRST) != SC_SUCCESS
  7445.                   printf("%s\n",scemsg());
  7446.                 scddclose(ndx);
  7447.               }
  7448.               scdterm();
  7449.             }
  7450.  
  7451.  
  7452.  
  7453.                                          106
  7454.  
  7455.  
  7456.  
  7457.  
  7458.  
  7459.  
  7460.  
  7461.  
  7462.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7463.  
  7464.  
  7465.             
  7466.  
  7467.  
  7468.  
  7469.  
  7470.  
  7471.             scdkfirst 
  7472.  
  7473.  
  7474.  
  7475.  
  7476.             USAGE
  7477.                       signed int scdkfirst(
  7478.                            signed char handle,
  7479.                            signed char *key,
  7480.                            signed long *recno );
  7481.  
  7482.  
  7483.             PROTOTYPE IN
  7484.                       sc_base.h
  7485.  
  7486.  
  7487.             DESCRIPTION
  7488.                       scdkfirst will  set the current key pointer to the
  7489.                       first logical  key in the index and return the key
  7490.                       value  "key"   and  data   record  number  "recno"
  7491.                       associated with the new current key.
  7492.  
  7493.  
  7494.                       The user  must ensure  that  the  buffer  used  to
  7495.                       return the  key is large enough to hold the entire
  7496.                       key.  The   maximum  length  of  the  key  can  be
  7497.                       determined via a call to scdninfo.
  7498.  
  7499.  
  7500.                       Note that  numeric keys  are returned  as doubles,
  7501.                       and character keys are returned as strings.
  7502.  
  7503.  
  7504.             SEE ALSO
  7505.                       scdninfo.
  7506.  
  7507.  
  7508.             RETURN VALUE
  7509.                       SC_END    successfully found the first key
  7510.                       SC_BADHNDL     index file not open or bad handle
  7511.                       SC_EMPTY  index file empty - no keys found
  7512.                       SC_SKFAIL seek failure
  7513.                       SC_RDFAIL read index file failure
  7514.                       SC_NULLPARM    parameter address null
  7515.  
  7516.  
  7517.  
  7518.  
  7519.                                          107
  7520.  
  7521.  
  7522.  
  7523.  
  7524.  
  7525.  
  7526.  
  7527.  
  7528.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7529.  
  7530.  
  7531.             EXAMPLE
  7532.  
  7533.             /*
  7534.              *  Character Key Example
  7535.              */
  7536.             #include "sc_base.h"
  7537.             
  7538.             void main()
  7539.             {
  7540.               char ndx, character[9];
  7541.               long recno;
  7542.             
  7543.               scdinit(15);
  7544.               if (scdnopen(&ndx,"CHAR.NDX") == SC_SUCCESS) {
  7545.                 date[8] = 0;
  7546.                 scdkfirst(ndx,character,&recno);
  7547.                 printf("%s %ld\n",character,recno);
  7548.                 scdnclose(ndx);
  7549.               }
  7550.               scdterm();
  7551.             }
  7552.  
  7553.  
  7554.  
  7555.  
  7556.  
  7557.  
  7558.             /*
  7559.              *  Date Key Example
  7560.              */
  7561.             #include "sc_base.h"
  7562.             
  7563.             void main()
  7564.             {
  7565.               char ndx;
  7566.               double date;
  7567.               long recno;
  7568.             
  7569.               scdinit(15);
  7570.               if (scdnopen(&ndx,"DATE.NDX") == SC_SUCCESS) {
  7571.                 date[8] = 0;
  7572.                 scdkfirst(ndx,&date,&recno);
  7573.                 printf("%lf %ld\n",date,recno);
  7574.                 scdnclose(ndx);
  7575.               }
  7576.               scdterm();
  7577.             }
  7578.  
  7579.  
  7580.  
  7581.  
  7582.  
  7583.  
  7584.  
  7585.                                          108
  7586.  
  7587.  
  7588.  
  7589.  
  7590.  
  7591.  
  7592.  
  7593.  
  7594.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7595.  
  7596.  
  7597.             
  7598.  
  7599.  
  7600.  
  7601.  
  7602.  
  7603.             scdklast  
  7604.  
  7605.  
  7606.  
  7607.  
  7608.             USAGE
  7609.                       signed int scdklast(
  7610.                            signed char handle,
  7611.                            signed char *key,
  7612.                            signed long *recno );
  7613.  
  7614.  
  7615.             PROTOTYPE IN
  7616.                       sc_base.h
  7617.  
  7618.  
  7619.             DESCRIPTION
  7620.                       scdklast will  set the  current key pointer to the
  7621.                       last logical  key in  the index and return the key
  7622.                       value  "key"   and  data   record  number  "recno"
  7623.                       associated with the new current key.
  7624.  
  7625.  
  7626.                       The user  must ensure  that  the  buffer  used  to
  7627.                       return the  key is large enough to hold the entire
  7628.                       key.  The   maximum  length  of  the  key  can  be
  7629.                       determined via a call to scdninfo.
  7630.  
  7631.  
  7632.                       Note that  numeric keys  are returned  as doubles,
  7633.                       and character keys are returned as strings.
  7634.  
  7635.  
  7636.             SEE ALSO
  7637.                       scdninfo.
  7638.  
  7639.  
  7640.             RETURN VALUE
  7641.                       SC_END    successfully found the last key
  7642.                       SC_BADHNDL     index file not open or bad handle
  7643.                       SC_EMPTY  index file empty - no keys found
  7644.                       SC_SKFAIL seek failure
  7645.                       SC_RDFAIL read from index file failure
  7646.                       SC_NULLPARM    parameter address null
  7647.  
  7648.  
  7649.  
  7650.  
  7651.                                          109
  7652.  
  7653.  
  7654.  
  7655.  
  7656.  
  7657.  
  7658.  
  7659.  
  7660.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7661.  
  7662.  
  7663.             EXAMPLE
  7664.  
  7665.             /*
  7666.              *  Character Key Example
  7667.              */
  7668.             #include "sc_base.h"
  7669.             
  7670.             void main()
  7671.             {
  7672.               char ndx, character[9];
  7673.               long recno;
  7674.             
  7675.               scdinit(15);
  7676.               if (scdnopen(&ndx,"CHAR.NDX") == SC_SUCCESS) {
  7677.                 date[8] = 0;
  7678.                 scdklast(ndx,character,&recno);
  7679.                 printf("%s %ld\n",character,recno);
  7680.                 scdnclose(ndx);
  7681.               }
  7682.               scdterm();
  7683.             }
  7684.  
  7685.  
  7686.  
  7687.  
  7688.  
  7689.  
  7690.             /*
  7691.              *  Numeric Key Example
  7692.              */
  7693.             #include "sc_base.h"
  7694.             
  7695.             void main()
  7696.             {
  7697.               char ndx;
  7698.               double numeric;
  7699.               long recno;
  7700.             
  7701.               scdinit(15);
  7702.               if (scdnopen(&ndx,"NUMERIC.NDX") == SC_SUCCESS) {
  7703.                 date[8] = 0;
  7704.                 scdklast(ndx,&numeric,&recno);
  7705.                 printf("%lf %ld\n",numeric,recno);
  7706.                 scdnclose(ndx);
  7707.               }
  7708.               scdterm();
  7709.             }
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.  
  7717.                                          110
  7718.  
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7727.  
  7728.  
  7729.             
  7730.  
  7731.  
  7732.  
  7733.  
  7734.  
  7735.             scdkmake  
  7736.  
  7737.  
  7738.  
  7739.  
  7740.             USAGE
  7741.                       signed int scdkmake(
  7742.                            signed char datahandle,
  7743.                            signed char indexhandle,
  7744.                            void **key );
  7745.  
  7746.  
  7747.             PROTOTYPE IN
  7748.                       sc_base.h
  7749.  
  7750.  
  7751.             DESCRIPTION
  7752.                       scdkmake will  build an  index key  using the  key
  7753.                       expression  of   the  index   file  specified   by
  7754.                       "indexhandle" and  the data  found in  the  output
  7755.                       buffer of the data file "datahandle". Memory space
  7756.                       for the "key" will be allocated and the address of
  7757.                       this block will be returned.
  7758.  
  7759.  
  7760.                       The key  expression can consist of either the data
  7761.                       field name  or one  of five  dBASE functions  or a
  7762.                       combination thereof.  Data field  types  of  date,
  7763.                       numeric, or character are allowed. dBASE functions
  7764.                       dtoc, left,  right, str,  and substr are currently
  7765.                       supported by scdkmake.
  7766.  
  7767.  
  7768.                       Following is  a  brief  description  of  the  five
  7769.                       expression functions:
  7770.  
  7771.  
  7772.                       dtoc will  convert data  from a  date field  to an
  7773.                       ASCIIZ string of the format mm/dd/yy. Syntax is:
  7774.  
  7775.  
  7776.                       dtoc(field_name)
  7777.  
  7778.  
  7779.  
  7780.  
  7781.  
  7782.  
  7783.                                          111
  7784.  
  7785.  
  7786.  
  7787.  
  7788.  
  7789.  
  7790.  
  7791.  
  7792.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7793.  
  7794.  
  7795.                       left will  return the  left portion of a character
  7796.                       field  as   an  ASCIIZ   string.  The   number  of
  7797.                       characters returned  is specified  after the field
  7798.                       name. Syntax is:
  7799.  
  7800.  
  7801.                       left(field_name,number)
  7802.  
  7803.  
  7804.                       right will return the right portion of a character
  7805.                       field  as   an  ASCIIZ   string.  The   number  of
  7806.                       characters returned  is specified  after the field
  7807.                       name. This  is a  count from the right side of the
  7808.                       field. Syntax is:
  7809.  
  7810.  
  7811.                       right(field_name,number)
  7812.  
  7813.  
  7814.                       str will  convert a  numeric field  to  an  ASCIIZ
  7815.                       string. The  total length  of the  string and  the
  7816.                       number of  decimal places are optional parameters.
  7817.                       The default  string length is 10 and the number of
  7818.                       decimal places is 0. Syntax is:
  7819.  
  7820.  
  7821.                       str(field_name,length,decimal_places)
  7822.  
  7823.  
  7824.                       substr  will   return  the  middle  portion  of  a
  7825.                       character field.  The  starting  offset  into  the
  7826.                       field is  a  required  parameter.  The  number  of
  7827.                       characters to  be used  is an  optional  parameter
  7828.                       whose default value is the remainder of the field.
  7829.                       Syntax is:
  7830.  
  7831.  
  7832.                       substr(field_name,start,count)
  7833.  
  7834.  
  7835.                       An example of a more complex key expression:
  7836.  
  7837.  
  7838.                       right(dtoc(date),2)+left(dtoc(date,2)
  7839.  
  7840.  
  7841.                       This expression  would cause scdkmake to create an
  7842.                       index key  string consisting of the year and month
  7843.                       ("yymm"). For example if date equals "2/13/89" the
  7844.                       resultant key would be "8902".
  7845.  
  7846.  
  7847.  
  7848.  
  7849.                                          112
  7850.  
  7851.  
  7852.  
  7853.  
  7854.  
  7855.  
  7856.  
  7857.  
  7858.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7859.  
  7860.  
  7861.                       Note that  for key  expressions consisting of only
  7862.                       one data  field scdkmake  is probably an overkill.
  7863.                       You can  easily generate  these keys yourself. See
  7864.                       scdkdate for  information on  date string  to  key
  7865.                       translation. scdkmake is a fairly large module and
  7866.                       if not  needed probably  should not  be used. This
  7867.                       function is  best used  when the key expression is
  7868.                       more complex.
  7869.  
  7870.  
  7871.                       Note that  memory is  allocated for  the generated
  7872.                       key and  it is the responsibility of the caller to
  7873.                       free this memory when finished.
  7874.  
  7875.  
  7876.             SEE ALSO
  7877.                       scdncreate, scdkdate, scdkmakex.
  7878.  
  7879.  
  7880.             RETURN VALUE
  7881.                       SC_SUCCESS     key created
  7882.                       SC_BADHNDL     index file not open or bad handle
  7883.                       SC_MEMERR memory allocation failure
  7884.                       SC_BADEXPR     invalid key expression
  7885.                       SC_NULLPARM    parameter address null
  7886.                       SC_BADFLDN     invalid field name
  7887.  
  7888.  
  7889.             EXAMPLE
  7890.  
  7891.             #include "sc_base.h"
  7892.             
  7893.             void main()
  7894.             {
  7895.               char ndx, dbf, char *key, date[9];
  7896.               long recno;
  7897.             
  7898.               scdinit(15);
  7899.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  7900.                 if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  7901.                   scdfput(dbf,0,&date);
  7902.                   scdrput(dbf,&recno,SC_ADD);
  7903.                   scdkmake(dbf,ndx,(void **) &key);
  7904.                   scdkadd(ndx,key,recno);
  7905.                   free(key);         /* free memory allocated for key */
  7906.                   scdnclose(ndx);
  7907.                 }
  7908.                 scddclose(dbf);
  7909.               }
  7910.               scdterm();
  7911.             }
  7912.  
  7913.  
  7914.  
  7915.                                          113
  7916.  
  7917.  
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7925.  
  7926.  
  7927.             
  7928.  
  7929.  
  7930.  
  7931.  
  7932.  
  7933.             scdkmakex 
  7934.  
  7935.  
  7936.  
  7937.  
  7938.             USAGE
  7939.                       signed int scdkmakex(
  7940.                            signed char datahandle,
  7941.                            signed char indexhandle,
  7942.                            void **key,
  7943.                            signed int buffer );
  7944.  
  7945.  
  7946.             PROTOTYPE IN
  7947.                       sc_base.h
  7948.  
  7949.  
  7950.             DESCRIPTION
  7951.                       scdkmakex is  an extended  form of  scdkmake which
  7952.                       enables the use of either I/O buffer. Which buffer
  7953.                       used is  determined by  "buffer": SC_INPUT - input
  7954.                       buffer, SC_OUTPUT - output buffer.
  7955.  
  7956.  
  7957.             SEE ALSO
  7958.                       scdkmake
  7959.  
  7960.  
  7961.             RETURN VALUE
  7962.                       SC_SUCCESS     key created
  7963.                       SC_BADHNDL     index file not open or bad handle
  7964.                       SC_MEMERR memory allocation failure
  7965.                       SC_BADEXPR     invalid key expression
  7966.                       SC_NULLPARM    parameter address null
  7967.                       SC_BADFLDN     invalid field name
  7968.                       SC_BADCMD invalid I/O buffer selection
  7969.  
  7970.  
  7971.             EXAMPLE
  7972.  
  7973.             #include "sc_base.h"
  7974.             
  7975.             void main()
  7976.             {
  7977.               char ndx, dbf, char *key, date[9];
  7978.  
  7979.  
  7980.  
  7981.                                          114
  7982.  
  7983.  
  7984.  
  7985.  
  7986.  
  7987.  
  7988.  
  7989.  
  7990.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  7991.  
  7992.  
  7993.               long recno;
  7994.             
  7995.               scdinit(15);
  7996.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  7997.                 if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  7998.                   scdfput(dbf,0,&date);
  7999.                   scdrput(dbf,&recno,SC_ADD);
  8000.                   scdkmakex(dbf,ndx,(void **) &key, SC_OUTPUT);
  8001.                   scdkadd(ndx,key,recno);
  8002.                   free(key);         /* free memory allocated for key */
  8003.                   scdnclose(ndx);
  8004.                 }
  8005.                 scddclose(dbf);
  8006.               }
  8007.               scdterm();
  8008.             }
  8009.  
  8010.  
  8011.  
  8012.  
  8013.  
  8014.  
  8015.  
  8016.  
  8017.  
  8018.  
  8019.  
  8020.  
  8021.  
  8022.  
  8023.  
  8024.  
  8025.  
  8026.  
  8027.  
  8028.  
  8029.  
  8030.  
  8031.  
  8032.  
  8033.  
  8034.  
  8035.  
  8036.  
  8037.  
  8038.  
  8039.  
  8040.  
  8041.  
  8042.  
  8043.  
  8044.  
  8045.  
  8046.  
  8047.                                          115
  8048.  
  8049.  
  8050.  
  8051.  
  8052.  
  8053.  
  8054.  
  8055.  
  8056.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8057.  
  8058.  
  8059.             
  8060.  
  8061.  
  8062.  
  8063.  
  8064.  
  8065.             scdknext  
  8066.  
  8067.  
  8068.  
  8069.  
  8070.             USAGE
  8071.                       signed int scdknext(
  8072.                            signed char handle,
  8073.                            signed char *key,
  8074.                            signed long *recno );
  8075.  
  8076.  
  8077.             PROTOTYPE IN
  8078.                       sc_base.h
  8079.  
  8080.  
  8081.             DESCRIPTION
  8082.                       scdknext will increment the key pointer and return
  8083.                       the key value "key" and data record number "recno"
  8084.                       associated with the new current key.
  8085.  
  8086.  
  8087.                       If scdknext  is called  immediately after  opening
  8088.                       the index  file the  first  logical  key  will  be
  8089.                       returned.
  8090.  
  8091.  
  8092.                       The user  must ensure  that  the  buffer  used  to
  8093.                       return the  key is large enough to hold the entire
  8094.                       key.  The   maximum  length  of  the  key  can  be
  8095.                       determined via a call to scdninfo.
  8096.  
  8097.  
  8098.                       Note that  numeric keys  are returned  as doubles,
  8099.                       and character keys are returned as strings.
  8100.  
  8101.  
  8102.             SEE ALSO
  8103.                       scdninfo.
  8104.  
  8105.  
  8106.             RETURN VALUE
  8107.                       SC_SUCCESS     successfully returned "key" and
  8108.                                      "recno"
  8109.                       SC_BADHNDL     index file not open or bad handle
  8110.  
  8111.  
  8112.  
  8113.                                          116
  8114.  
  8115.  
  8116.  
  8117.  
  8118.  
  8119.  
  8120.  
  8121.  
  8122.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8123.  
  8124.  
  8125.                       SC_END    success but at end of index file
  8126.                       SC_RDFAIL index file read failure
  8127.                       SC_SKFAIL seek failure (bad record address or seek
  8128.                                      failed)
  8129.                       SC_NULLPARM    parameter address null
  8130.  
  8131.  
  8132.             EXAMPLE
  8133.  
  8134.             /*
  8135.              *  Character Key Example
  8136.              */
  8137.             #include "sc_base.h"
  8138.             
  8139.             void main()
  8140.             {
  8141.               char ndx, character[9];
  8142.               long recno;
  8143.             
  8144.               scdinit(15);
  8145.               if (scdnopen(&ndx,"CHAR.NDX") == SC_SUCCESS) {
  8146.                 scdknext(ndx,character,&recno);     /* return first key
  8147.             */
  8148.                 printf("%s %ld\n",character,recno);
  8149.                 scdnclose(ndx);
  8150.               }
  8151.               scdterm();
  8152.             }
  8153.  
  8154.  
  8155.  
  8156.  
  8157.  
  8158.  
  8159.             /*
  8160.              *  Numeric Key Example
  8161.              */
  8162.             #include "sc_base.h"
  8163.             
  8164.             void main()
  8165.             {
  8166.               char ndx;
  8167.               double numeric;
  8168.               long recno;
  8169.             
  8170.               scdinit(15);
  8171.               if (scdnopen(&ndx,"NUMERIC.NDX") == SC_SUCCESS) {
  8172.                 scdknext(ndx,&numeric,&recno); /* return first key */
  8173.                 printf("%lf %ld\n",numeric,recno);
  8174.                 scdnclose(ndx);
  8175.               }
  8176.  
  8177.  
  8178.  
  8179.                                          117
  8180.  
  8181.  
  8182.  
  8183.  
  8184.  
  8185.  
  8186.  
  8187.  
  8188.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8189.  
  8190.  
  8191.               scdterm();
  8192.             }
  8193.  
  8194.  
  8195.  
  8196.  
  8197.  
  8198.  
  8199.  
  8200.  
  8201.  
  8202.  
  8203.  
  8204.  
  8205.  
  8206.  
  8207.  
  8208.  
  8209.  
  8210.  
  8211.  
  8212.  
  8213.  
  8214.  
  8215.  
  8216.  
  8217.  
  8218.  
  8219.  
  8220.  
  8221.  
  8222.  
  8223.  
  8224.  
  8225.  
  8226.  
  8227.  
  8228.  
  8229.  
  8230.  
  8231.  
  8232.  
  8233.  
  8234.  
  8235.  
  8236.  
  8237.  
  8238.  
  8239.  
  8240.  
  8241.  
  8242.  
  8243.  
  8244.  
  8245.                                          118
  8246.  
  8247.  
  8248.  
  8249.  
  8250.  
  8251.  
  8252.  
  8253.  
  8254.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8255.  
  8256.  
  8257.             
  8258.  
  8259.  
  8260.  
  8261.  
  8262.  
  8263.             scdkprev  
  8264.  
  8265.  
  8266.  
  8267.  
  8268.             USAGE
  8269.                       signed int scdkprev(
  8270.                            signed char handle,
  8271.                            signed char *key,
  8272.                            signed long *recno );
  8273.  
  8274.  
  8275.             PROTOTYPE IN
  8276.                       sc_base.h
  8277.  
  8278.  
  8279.             DESCRIPTION
  8280.                       scdkprev will decrement the key pointer and return
  8281.                       the key value "key" and data record number "recno"
  8282.                       associated with the new current key.
  8283.  
  8284.  
  8285.                       If scdkprev  is called  immediately after  opening
  8286.                       the index  file  the  last  logical  key  will  be
  8287.                       returned.
  8288.  
  8289.  
  8290.                       The user  must ensure  that  the  buffer  used  to
  8291.                       return the  key is large enough to hold the entire
  8292.                       key.  The   maximum  length  of  the  key  can  be
  8293.                       determined via a call to scdninfo.
  8294.  
  8295.  
  8296.                       Note that  numeric keys  are returned  as doubles,
  8297.                       and character keys are returned as strings.
  8298.  
  8299.  
  8300.             SEE ALSO
  8301.                       scdninfo.
  8302.  
  8303.  
  8304.             RETURN VALUE
  8305.                       SC_SUCCESS     successfully returned "key" and
  8306.                                      "recno"
  8307.                       SC_BADHNDL     index file not open or bad handle
  8308.  
  8309.  
  8310.  
  8311.                                          119
  8312.  
  8313.  
  8314.  
  8315.  
  8316.  
  8317.  
  8318.  
  8319.  
  8320.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8321.  
  8322.  
  8323.                       SC_END    success but at end of index file
  8324.                       SC_RDFAIL index file read failure
  8325.                       SC_SKFAIL index file record seek failure
  8326.                       SC_NULLPARM    parameter address null
  8327.  
  8328.  
  8329.             EXAMPLE
  8330.  
  8331.             /*
  8332.              *  Character Key Example
  8333.              */
  8334.             #include "sc_base.h"
  8335.             
  8336.             void main()
  8337.             {
  8338.               char ndx, character[9];
  8339.               long recno;
  8340.             
  8341.               scdinit(15);
  8342.               if (scdnopen(&ndx,"CHAR.NDX") == SC_SUCCESS) {
  8343.                 scdkprev(ndx,character,&recno);     /* get last key */
  8344.                 printf("%s %ld\n",character,recno);
  8345.                 scdnclose(ndx);
  8346.               }
  8347.               scdterm();
  8348.             }
  8349.  
  8350.  
  8351.  
  8352.  
  8353.  
  8354.  
  8355.             /*
  8356.              *  Date Key Example
  8357.              */
  8358.             #include "sc_base.h"
  8359.             
  8360.             void main()
  8361.             {
  8362.               char ndx;
  8363.               double date;
  8364.               long recno;
  8365.             
  8366.               scdinit(15);
  8367.               if (scdnopen(&ndx,"DATE.NDX") == SC_SUCCESS) {
  8368.                 scdkprev(ndx,&date,&recno);    /* get last key */
  8369.                 printf("%lf %ld\n",date,recno);
  8370.                 scdnclose(ndx);
  8371.               }
  8372.               scdterm();
  8373.             }
  8374.  
  8375.  
  8376.  
  8377.                                          120
  8378.  
  8379.  
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8387.  
  8388.  
  8389.             
  8390.  
  8391.  
  8392.  
  8393.  
  8394.  
  8395.             scdnclose 
  8396.  
  8397.  
  8398.  
  8399.  
  8400.             USAGE
  8401.                       signed int scdnclose(
  8402.                            signed char handle );
  8403.  
  8404.  
  8405.             PROTOTYPE IN
  8406.                       sc_base.h
  8407.  
  8408.  
  8409.             DESCRIPTION
  8410.                       scdnclose closes  an  index  file  and  frees  all
  8411.                       allocated memory associated with index file.
  8412.  
  8413.  
  8414.             RETURN VALUE
  8415.                       SC_SUCCESS     index file closed
  8416.                       SC_CLOSFAIL    file close failure
  8417.                       SC_BADHNDL     index file not open or bad handle
  8418.  
  8419.  
  8420.             EXAMPLE
  8421.  
  8422.             #include "sc_base.h"
  8423.             
  8424.             void main()
  8425.             {
  8426.               char ndx;
  8427.             
  8428.               scdinit(15);
  8429.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS)
  8430.                 scdnclose(ndx);
  8431.               scdterm();
  8432.             }
  8433.  
  8434.  
  8435.  
  8436.  
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442.  
  8443.                                          121
  8444.  
  8445.  
  8446.  
  8447.  
  8448.  
  8449.  
  8450.  
  8451.  
  8452.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8453.  
  8454.  
  8455.             
  8456.  
  8457.  
  8458.  
  8459.  
  8460.  
  8461.             scdncreate     
  8462.  
  8463.  
  8464.  
  8465.  
  8466.             USAGE
  8467.                       signed int scdncreate(
  8468.                            signed char *filename,
  8469.                            signed char keytype,
  8470.                            signed char *keyexpr,
  8471.                            signed char keylen );
  8472.  
  8473.  
  8474.             PROTOTYPE IN
  8475.                       sc_base.h
  8476.  
  8477.  
  8478.             DESCRIPTION
  8479.                       scdncreate creates  an index  file. "keyexpr" will
  8480.                       be translated  to all  upper case  when the  index
  8481.                       file is created.
  8482.  
  8483.  
  8484.                       If "keytype"  is 'c',  then "keyexpr"  must be  an
  8485.                       ASCIIZ string  consisting of  one  or  more  field
  8486.                       names from the data record. All fields included in
  8487.                       the  expression   must  be   of  type  'c'  or  be
  8488.                       translated into  type 'c'.  No check  is  made  to
  8489.                       verify this.  "keyexpr" cannot  be longer that 220
  8490.                       characters. "keylen" cannot exceed 100.
  8491.  
  8492.  
  8493.                       If "keytype"  is 'n' or 'd', then "keyexpr" should
  8494.                       consist of  only one  data  field.  "keylen"  will
  8495.                       automatically be  set to  8 (numeric and date keys
  8496.                       are stored  as doubles). For both date and numeric
  8497.                       keys "keytype" will be forced to 'n'.
  8498.  
  8499.  
  8500.                       NOTE: scdncreate will create a new index file even
  8501.                       if one had already existed.
  8502.  
  8503.  
  8504.                       NOTE: "keyexpr" is used by dBASE. "keyexpr" is NOT
  8505.                       checked for  validity  during  the  file  creation
  8506.  
  8507.  
  8508.  
  8509.                                          122
  8510.  
  8511.  
  8512.  
  8513.  
  8514.  
  8515.  
  8516.  
  8517.  
  8518.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8519.  
  8520.  
  8521.                       process. Currently only the scdkmake function uses
  8522.                       "keyexpr".
  8523.  
  8524.  
  8525.             SEE ALSO
  8526.                       scdkmake.
  8527.  
  8528.  
  8529.             RETURN VALUE
  8530.                       SC_SUCCESS     index file created
  8531.                       SC_WRTFAIL     disk write failure
  8532.                       SC_BADEXPR     invalid keytype or bad keyexpr
  8533.                       SC_NOHNDL no DOS handles available
  8534.                       SC_NULLPARM    parameter address null
  8535.                       SC_BADKEYT     invalid key type
  8536.                       SC_KEYLEN invalid key length
  8537.                       SC_BADFNAME    invalid filename
  8538.  
  8539.  
  8540.             EXAMPLE
  8541.  
  8542.             #include "sc_base.h"
  8543.             
  8544.             void main()
  8545.             {
  8546.               scdinit(15);
  8547.               scdncreate("TEST.NDX",'d',"date",8);
  8548.               scdterm();
  8549.             }
  8550.  
  8551.  
  8552.  
  8553.  
  8554.  
  8555.  
  8556.  
  8557.  
  8558.  
  8559.  
  8560.  
  8561.  
  8562.  
  8563.  
  8564.  
  8565.  
  8566.  
  8567.  
  8568.  
  8569.  
  8570.  
  8571.  
  8572.  
  8573.  
  8574.  
  8575.                                          123
  8576.  
  8577.  
  8578.  
  8579.  
  8580.  
  8581.  
  8582.  
  8583.  
  8584.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8585.  
  8586.  
  8587.             
  8588.  
  8589.  
  8590.  
  8591.  
  8592.  
  8593.             scdnexpr  
  8594.  
  8595.  
  8596.  
  8597.  
  8598.             USAGE
  8599.                       signed int scdnexpr(
  8600.                            signed char handle,
  8601.                            signed char *keyexpr );
  8602.  
  8603.  
  8604.             PROTOTYPE IN
  8605.                       sc_base.h
  8606.  
  8607.  
  8608.             DESCRIPTION
  8609.                       scdnexpr gets the index key expression and returns
  8610.                       it as an ASCIIZ string into a user supplied buffer
  8611.                       "keyexpr". The user must ensure that the buffer is
  8612.                       large enough  (the key  expression length  can  be
  8613.                       determined via  a call  to scdninfo)  to hold  the
  8614.                       entire key expression.
  8615.  
  8616.  
  8617.                       A NULL  byte will  be appended  to the  end of the
  8618.                       expression string returned. If you are dynamically
  8619.                       allocating memory be sure to make the buffer large
  8620.                       enough.
  8621.  
  8622.  
  8623.             SEE ALSO
  8624.                       scdninfo.
  8625.  
  8626.  
  8627.             RETURN VALUE
  8628.                       SC_SUCCESS     returned the key expression string
  8629.                       SC_BADHNDL     index file not open or bad handle
  8630.                       SC_NULLPARM    parameter address null
  8631.  
  8632.  
  8633.             EXAMPLE
  8634.  
  8635.             #include "sc_base.h"
  8636.             
  8637.             void main()
  8638.  
  8639.  
  8640.  
  8641.                                          124
  8642.  
  8643.  
  8644.  
  8645.  
  8646.  
  8647.  
  8648.  
  8649.  
  8650.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8651.  
  8652.  
  8653.             {
  8654.               char ndx, buffer[512];
  8655.             
  8656.               scdinit(15);
  8657.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  8658.                 scdnexpr(ndx,buffer);
  8659.                 printf("key expression = %s",buffer);
  8660.                 scdnclose(ndx);
  8661.               }
  8662.               scdterm();
  8663.             }
  8664.  
  8665.  
  8666.  
  8667.  
  8668.  
  8669.  
  8670.  
  8671.  
  8672.  
  8673.  
  8674.  
  8675.  
  8676.  
  8677.  
  8678.  
  8679.  
  8680.  
  8681.  
  8682.  
  8683.  
  8684.  
  8685.  
  8686.  
  8687.  
  8688.  
  8689.  
  8690.  
  8691.  
  8692.  
  8693.  
  8694.  
  8695.  
  8696.  
  8697.  
  8698.  
  8699.  
  8700.  
  8701.  
  8702.  
  8703.  
  8704.  
  8705.  
  8706.  
  8707.                                          125
  8708.  
  8709.  
  8710.  
  8711.  
  8712.  
  8713.  
  8714.  
  8715.  
  8716.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8717.  
  8718.  
  8719.             
  8720.  
  8721.  
  8722.  
  8723.  
  8724.  
  8725.             scdninfo  
  8726.  
  8727.  
  8728.  
  8729.  
  8730.             USAGE
  8731.                       signed int scdninfo(
  8732.                            signed char handle,
  8733.                            signed char *filename,
  8734.                            signed char *keytype,
  8735.                            signed char *keylen,
  8736.                            signed int *exprlen );
  8737.  
  8738.  
  8739.             PROTOTYPE IN
  8740.                       sc_base.h
  8741.  
  8742.  
  8743.             DESCRIPTION
  8744.                       scdninfo gets  the  filename  of  the  index  file
  8745.                       associated  with  "handle",  the  index  key  type
  8746.                       "keytype", the  maximum index key length "keylen",
  8747.                       and  the   length  of  the  index  key  expression
  8748.                       "exprlen".
  8749.  
  8750.  
  8751.                       If you are using "exprlen" to dynamically allocate
  8752.                       memory to  hold the  key expression be sure to add
  8753.                       one to the length before allocation.
  8754.  
  8755.  
  8756.             SEE ALSO
  8757.                       scdnopen.
  8758.  
  8759.  
  8760.             RETURN VALUE
  8761.                       SC_SUCCESS     returned index file information
  8762.                       SC_BADHNDL     index file not open or bad handle
  8763.                       SC_NULLPARM    parameter address null
  8764.  
  8765.  
  8766.             EXAMPLE
  8767.  
  8768.             #include <dir.h>
  8769.             #include "sc_base.h"
  8770.  
  8771.  
  8772.  
  8773.                                          126
  8774.  
  8775.  
  8776.  
  8777.  
  8778.  
  8779.  
  8780.  
  8781.  
  8782.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8783.  
  8784.  
  8785.             
  8786.             void main()
  8787.             {
  8788.               char ndx, filename[MAXPATH], keytype, keylen, exprlen;
  8789.             
  8790.               scdinit(15);
  8791.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  8792.                 scdninfo(ndx,filename,&keytype,&keylen,&exprlen);
  8793.                 printf("File name = %s\n",filename);
  8794.                 printf("Index key type = %c\n",keytype);
  8795.                 printf("Maximum key length = %d\n",keylen);
  8796.                 printf("Key expression length = %d\n",exprlen);
  8797.                 scdnclose(ndx);
  8798.               }
  8799.               scdterm();
  8800.             }
  8801.  
  8802.  
  8803.  
  8804.  
  8805.  
  8806.  
  8807.  
  8808.  
  8809.  
  8810.  
  8811.  
  8812.  
  8813.  
  8814.  
  8815.  
  8816.  
  8817.  
  8818.  
  8819.  
  8820.  
  8821.  
  8822.  
  8823.  
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.  
  8830.  
  8831.  
  8832.  
  8833.  
  8834.  
  8835.  
  8836.  
  8837.  
  8838.  
  8839.                                          127
  8840.  
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8849.  
  8850.  
  8851.             
  8852.  
  8853.  
  8854.  
  8855.  
  8856.  
  8857.             scdnopen  
  8858.  
  8859.  
  8860.  
  8861.  
  8862.             USAGE
  8863.                       signed int scdnopen(
  8864.                            signed char *handle,
  8865.                            signed char *filename );
  8866.  
  8867.  
  8868.             PROTOTYPE IN
  8869.                       sc_base.h
  8870.  
  8871.  
  8872.             DESCRIPTION
  8873.                       scdnopen opens  an index  file (.NDX). Memory will
  8874.                       be allocated  for a  file packet, I/O buffers, and
  8875.                       other miscellaneous  structures for use internally
  8876.                       by the  SoftC Database  Library file  manager. The
  8877.                       index file  will be  tested as much as possible to
  8878.                       insure that it is a legitimate dBASE index file.
  8879.  
  8880.  
  8881.                       The index  expression will  be translated to upper
  8882.                       case after being read from the index file.
  8883.  
  8884.  
  8885.             RETURN VALUE
  8886.                       SC_SUCCESS     index file opened
  8887.                       SC_MEMERR memory allocation failure
  8888.                       SC_NOFILE      index file not found
  8889.                       SC_RDFAIL disk read failure
  8890.                       SC_SKFAIL disk seek failure
  8891.                       SC_NOHNDL no SoftC handles available
  8892.                       SC_BADFNAME    invalid filename
  8893.                       SC_NULLPARM    parameter address null
  8894.                       SC_KEYLEN invalid key length
  8895.                       SC_ITEMLEN     invalid key item length
  8896.                       SC_BADROOT     invalid root page number
  8897.                       SC_MAXKEYS     bad maximum number of keys
  8898.                       SC_FILENGTH    invalid file length
  8899.                       SC_BADKEYT     invalid key type
  8900.  
  8901.  
  8902.  
  8903.  
  8904.  
  8905.                                          128
  8906.  
  8907.  
  8908.  
  8909.  
  8910.  
  8911.  
  8912.  
  8913.  
  8914.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8915.  
  8916.  
  8917.             EXAMPLE
  8918.  
  8919.             #include "sc_base.h"
  8920.             
  8921.             void main()
  8922.             {
  8923.               char ndx;
  8924.             
  8925.               scdinit(15);
  8926.               if (scdnopen(&ndx,"UNKNOWN.NDX") == SC_SUCCESS) {
  8927.                 scdnclose(ndx);
  8928.               }
  8929.               scdterm();
  8930.             }
  8931.  
  8932.  
  8933.  
  8934.  
  8935.  
  8936.  
  8937.  
  8938.  
  8939.  
  8940.  
  8941.  
  8942.  
  8943.  
  8944.  
  8945.  
  8946.  
  8947.  
  8948.  
  8949.  
  8950.  
  8951.  
  8952.  
  8953.  
  8954.  
  8955.  
  8956.  
  8957.  
  8958.  
  8959.  
  8960.  
  8961.  
  8962.  
  8963.  
  8964.  
  8965.  
  8966.  
  8967.  
  8968.  
  8969.  
  8970.  
  8971.                                          129
  8972.  
  8973.  
  8974.  
  8975.  
  8976.  
  8977.  
  8978.  
  8979.  
  8980.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  8981.  
  8982.  
  8983.             
  8984.  
  8985.  
  8986.  
  8987.  
  8988.  
  8989.             scdpinfo  
  8990.  
  8991.  
  8992.  
  8993.  
  8994.             USAGE
  8995.                       signed int scdpinfo(
  8996.                            signed char handle,
  8997.                            signed char *numpgs );
  8998.  
  8999.  
  9000.             PROTOTYPE IN
  9001.                       sc_base.h
  9002.  
  9003.  
  9004.             DESCRIPTION
  9005.                       scdpinfo gets  the maximum  number of  index pages
  9006.                       the library  file manager  can keep  in memory and
  9007.                       returns it via "numpgs".
  9008.  
  9009.  
  9010.             RETURN VALUE
  9011.                       SC_SUCCESS     max number of pages allowed
  9012.                                      returned
  9013.                       SC_BADHNDL     index file not open or bad handle
  9014.                       SC_NULLPARM    parameter address null
  9015.  
  9016.  
  9017.             EXAMPLE
  9018.  
  9019.             #include "sc_base.h"
  9020.             
  9021.             void main()
  9022.             {
  9023.               char ndx, numpgs;
  9024.             
  9025.               scdinit(15);
  9026.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  9027.                 scdpinfo(ndx,&numpgs) == SC_SUCCESS)
  9028.                 printf("Maximum number of pages = %d\n",numpgs);
  9029.                 scdnclose(ndx);
  9030.               }
  9031.               scdterm();
  9032.             }
  9033.  
  9034.  
  9035.  
  9036.  
  9037.                                          130
  9038.  
  9039.  
  9040.  
  9041.  
  9042.  
  9043.  
  9044.  
  9045.  
  9046.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9047.  
  9048.  
  9049.             
  9050.  
  9051.  
  9052.  
  9053.  
  9054.  
  9055.             scdpnum   
  9056.  
  9057.  
  9058.  
  9059.  
  9060.             USAGE
  9061.                       signed int scdpnum(
  9062.                            signed char handle,
  9063.                            signed char *numpgs );
  9064.  
  9065.  
  9066.             PROTOTYPE IN
  9067.                       sc_base.h
  9068.  
  9069.  
  9070.             DESCRIPTION
  9071.                       scdpnum sets  the maximum  number of  index  pages
  9072.                       "numpgs" the  library file  manager  can  keep  in
  9073.                       memory. Memory  for index  pages will  be freed or
  9074.                       allocated as appropriate.
  9075.  
  9076.  
  9077.             RETURN VALUE
  9078.                       SC_SUCCESS     new max number of pages allowed
  9079.                                      returned
  9080.                       SC_BADHNDL     index file was open or bad handle
  9081.                       SC_BADCMD invalid new number of pages requested
  9082.                       SC_NULLPARM    parameter address null
  9083.  
  9084.  
  9085.             EXAMPLE
  9086.  
  9087.             #include "sc_base.h"
  9088.             
  9089.             void main()
  9090.             {
  9091.               char ndx, numpgs = 5;
  9092.             
  9093.               scdinit(15);
  9094.               if (scdnopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
  9095.                 scdpnum(ndx,&numpgs);
  9096.                 scdpinfo(ndx,&numpgs);
  9097.                 printf("New max = %d\n",numpgs);
  9098.                 scdnclose(ndx);
  9099.               }
  9100.  
  9101.  
  9102.  
  9103.                                          131
  9104.  
  9105.  
  9106.  
  9107.  
  9108.  
  9109.  
  9110.  
  9111.  
  9112.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9113.  
  9114.  
  9115.               scdterm();
  9116.             }
  9117.  
  9118.  
  9119.  
  9120.  
  9121.  
  9122.  
  9123.  
  9124.  
  9125.  
  9126.  
  9127.  
  9128.  
  9129.  
  9130.  
  9131.  
  9132.  
  9133.  
  9134.  
  9135.  
  9136.  
  9137.  
  9138.  
  9139.  
  9140.  
  9141.  
  9142.  
  9143.  
  9144.  
  9145.  
  9146.  
  9147.  
  9148.  
  9149.  
  9150.  
  9151.  
  9152.  
  9153.  
  9154.  
  9155.  
  9156.  
  9157.  
  9158.  
  9159.  
  9160.  
  9161.  
  9162.  
  9163.  
  9164.  
  9165.  
  9166.  
  9167.  
  9168.  
  9169.                                          132
  9170.  
  9171.  
  9172.  
  9173.  
  9174.  
  9175.  
  9176.  
  9177.  
  9178.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9179.  
  9180.  
  9181.             
  9182.  
  9183.  
  9184.  
  9185.  
  9186.  
  9187.             scdrclear 
  9188.  
  9189.  
  9190.  
  9191.  
  9192.             USAGE
  9193.                       signed int scdrclear(
  9194.                            signed char handle,
  9195.                            signed int buffer );
  9196.  
  9197.  
  9198.             PROTOTYPE IN
  9199.                       sc_base.h
  9200.  
  9201.  
  9202.             DESCRIPTION
  9203.                       scdrclear  clears  a  data  I/O  buffer.  "buffer"
  9204.                       indicates which record buffer to clear.
  9205.  
  9206.  
  9207.                       "buffer" =     clears this buffer
  9208.                         SC_INPUT     input
  9209.                         SC_OUTPUT    output
  9210.  
  9211.  
  9212.                       The selected buffer will be written with spaces ("
  9213.                       ") NOT zeros (0).
  9214.  
  9215.  
  9216.             RETURN VALUE
  9217.                       SC_SUCCESS     buffer cleared
  9218.                       SC_BADHNDL     data file not open or bad handle
  9219.                       SC_BADCMD invalid buffer
  9220.  
  9221.  
  9222.             EXAMPLE
  9223.  
  9224.             #include "sc_base.h"
  9225.             
  9226.             void main()
  9227.             {
  9228.               char dbf, character[17] = "Hello World!";
  9229.             
  9230.               scdinit(15);
  9231.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9232.  
  9233.  
  9234.  
  9235.                                          133
  9236.  
  9237.  
  9238.  
  9239.  
  9240.  
  9241.  
  9242.  
  9243.  
  9244.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9245.  
  9246.  
  9247.                 scdfputs(dbf,0,"SoftC Database Library   ");
  9248.                 scdrclear(dbf,SC_INPUT);
  9249.                 scdrcopy(dbf,SC_OUTPUT);
  9250.                 scdfgets(dbf,0,character);
  9251.                 printf("%s\n",character);
  9252.               }
  9253.               scdterm();
  9254.             }
  9255.  
  9256.  
  9257.  
  9258.  
  9259.  
  9260.  
  9261.  
  9262.  
  9263.  
  9264.  
  9265.  
  9266.  
  9267.  
  9268.  
  9269.  
  9270.  
  9271.  
  9272.  
  9273.  
  9274.  
  9275.  
  9276.  
  9277.  
  9278.  
  9279.  
  9280.  
  9281.  
  9282.  
  9283.  
  9284.  
  9285.  
  9286.  
  9287.  
  9288.  
  9289.  
  9290.  
  9291.  
  9292.  
  9293.  
  9294.  
  9295.  
  9296.  
  9297.  
  9298.  
  9299.  
  9300.  
  9301.                                          134
  9302.  
  9303.  
  9304.  
  9305.  
  9306.  
  9307.  
  9308.  
  9309.  
  9310.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9311.  
  9312.  
  9313.             
  9314.  
  9315.  
  9316.  
  9317.  
  9318.  
  9319.             scdrcopy  
  9320.  
  9321.  
  9322.  
  9323.  
  9324.             USAGE
  9325.                       signed int scdrcopy(
  9326.                            signed char handle,
  9327.                            signed int buffer );
  9328.  
  9329.  
  9330.             PROTOTYPE IN
  9331.                       sc_base.h
  9332.  
  9333.  
  9334.             DESCRIPTION
  9335.                       scdrcopy copies  the contents of one I/O buffer to
  9336.                       the other. "buffer" indicates the direction of the
  9337.                       copy.
  9338.  
  9339.  
  9340.                       "buffer" =     copies this way
  9341.                         SC_INPUT     input to output
  9342.                         SC_OUTPUT    output to input
  9343.  
  9344.  
  9345.             RETURN VALUE
  9346.                       SC_SUCCESS     buffer copied successfully
  9347.                       SC_BADHNDL     data file not open or bad handle
  9348.                       SC_BADCMD invalid buffer
  9349.  
  9350.  
  9351.             EXAMPLE
  9352.  
  9353.             #include "sc_base.h"
  9354.             
  9355.             void main()
  9356.             {
  9357.               char dbf, character[17] = "Hello World!";
  9358.             
  9359.               scdinit(15);
  9360.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9361.                 scdfputs(dbf,0,"SoftC Database Library   ");
  9362.                 scdrclear(dbf,SC_INPUT);
  9363.                 scdrcopy(dbf,SC_OUTPUT);
  9364.  
  9365.  
  9366.  
  9367.                                          135
  9368.  
  9369.  
  9370.  
  9371.  
  9372.  
  9373.  
  9374.  
  9375.  
  9376.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9377.  
  9378.  
  9379.                 scdfgets(dbf,0,character);
  9380.                 printf("%s\n",character);
  9381.                 scddclose(dbf);
  9382.               }
  9383.               scdterm();
  9384.             }
  9385.  
  9386.  
  9387.  
  9388.  
  9389.  
  9390.  
  9391.  
  9392.  
  9393.  
  9394.  
  9395.  
  9396.  
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.  
  9407.  
  9408.  
  9409.  
  9410.  
  9411.  
  9412.  
  9413.  
  9414.  
  9415.  
  9416.  
  9417.  
  9418.  
  9419.  
  9420.  
  9421.  
  9422.  
  9423.  
  9424.  
  9425.  
  9426.  
  9427.  
  9428.  
  9429.  
  9430.  
  9431.  
  9432.  
  9433.                                          136
  9434.  
  9435.  
  9436.  
  9437.  
  9438.  
  9439.  
  9440.  
  9441.  
  9442.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9443.  
  9444.  
  9445.             
  9446.  
  9447.  
  9448.  
  9449.  
  9450.  
  9451.             scdrdel   
  9452.  
  9453.  
  9454.  
  9455.  
  9456.             USAGE
  9457.                       signed int scdrdel(
  9458.                            signed char handle,
  9459.                            signed long recno );
  9460.  
  9461.  
  9462.             PROTOTYPE IN
  9463.                       sc_base.h
  9464.  
  9465.  
  9466.             DESCRIPTION
  9467.                       scdrdel will flag a record specified by "recno" as
  9468.                       'deleted'. To  maintain compatibility  with  dBASE
  9469.                       the data  record cannot  be reused,  but it can be
  9470.                       'undeleted' by scdrundel.
  9471.  
  9472.  
  9473.             SEE ALSO
  9474.                       scdrundel.
  9475.  
  9476.  
  9477.             RETURN VALUE
  9478.                       SC_SUCCESS     record marked 'deleted'
  9479.                       SC_BADHNDL     data file not open or bad handle
  9480.                       SC_SKFAIL invalid data record number or disk seek
  9481.                                      failure
  9482.                       SC_RDFAIL disk read failure
  9483.                       SC_WRTFAIL     disk write failure
  9484.  
  9485.  
  9486.             EXAMPLE
  9487.  
  9488.             #include "sc_base.h"
  9489.             
  9490.             void main()
  9491.             {
  9492.               char dbf;
  9493.             
  9494.               scdinit(15);
  9495.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9496.  
  9497.  
  9498.  
  9499.                                          137
  9500.  
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9509.  
  9510.  
  9511.                 scdrdel(dbf,1L);
  9512.                 scdrget(dbf,1L);
  9513.                 printf("%s\n",scemsg());
  9514.                 scddclose(dbf);
  9515.               }
  9516.               scdterm();
  9517.             }
  9518.  
  9519.  
  9520.  
  9521.  
  9522.  
  9523.  
  9524.  
  9525.  
  9526.  
  9527.  
  9528.  
  9529.  
  9530.  
  9531.  
  9532.  
  9533.  
  9534.  
  9535.  
  9536.  
  9537.  
  9538.  
  9539.  
  9540.  
  9541.  
  9542.  
  9543.  
  9544.  
  9545.  
  9546.  
  9547.  
  9548.  
  9549.  
  9550.  
  9551.  
  9552.  
  9553.  
  9554.  
  9555.  
  9556.  
  9557.  
  9558.  
  9559.  
  9560.  
  9561.  
  9562.  
  9563.  
  9564.  
  9565.                                          138
  9566.  
  9567.  
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9575.  
  9576.  
  9577.             
  9578.  
  9579.  
  9580.  
  9581.  
  9582.  
  9583.             scdrget   
  9584.  
  9585.  
  9586.  
  9587.  
  9588.             USAGE
  9589.                       signed int scdrget(
  9590.                            signed char handle,
  9591.                            signed long recno );
  9592.  
  9593.  
  9594.             PROTOTYPE IN
  9595.                       sc_base.h
  9596.  
  9597.  
  9598.             DESCRIPTION
  9599.                       scdrget will  read the  data record  specified  by
  9600.                       "recno"  from   the  data   file  associated  with
  9601.                       "handle" into the internal input buffer.
  9602.  
  9603.  
  9604.             SEE ALSO
  9605.                       scdfget, scdfput, scdrput.
  9606.  
  9607.  
  9608.             RETURN VALUE
  9609.                       SC_SUCCESS     record read
  9610.                       SC_BADHNDL     data file not open or bad handle
  9611.                       SC_SKFAIL invalid data record number or disk seek
  9612.                                      failure
  9613.                       SC_RDFAIL disk read failure
  9614.                       SC_DELREC record read was marked 'deleted'
  9615.  
  9616.  
  9617.             EXAMPLE
  9618.  
  9619.             #include "sc_base.h"
  9620.             
  9621.             void main()
  9622.             {
  9623.               char dbf, character[17] = "Hello",
  9624.                    logical = 'F', date[9] = "12/25/88";
  9625.               double numeric = 150.00L;
  9626.               unsigned long memo = 1L;
  9627.             
  9628.  
  9629.  
  9630.  
  9631.                                          139
  9632.  
  9633.  
  9634.  
  9635.  
  9636.  
  9637.  
  9638.  
  9639.  
  9640.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9641.  
  9642.  
  9643.               scdinit(15);
  9644.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9645.                 scdrget(dbf,1L);
  9646.                 scdfgets(dbf,0,character);
  9647.                 scdfgets(dbf,1,date);
  9648.                 scdfget(dbf,2,(void *) &logical);
  9649.                 scdfget(dbf,3,(void *) &memo);
  9650.                 scdfget(dbf,4,(void *) &numeric);
  9651.                 printf("%s %s %c %lu %lf\n",
  9652.                   character,date,logical,memo,numeric);
  9653.                 scddclose(dbf);
  9654.               }
  9655.               scdterm();
  9656.             }
  9657.  
  9658.  
  9659.  
  9660.  
  9661.  
  9662.  
  9663.  
  9664.  
  9665.  
  9666.  
  9667.  
  9668.  
  9669.  
  9670.  
  9671.  
  9672.  
  9673.  
  9674.  
  9675.  
  9676.  
  9677.  
  9678.  
  9679.  
  9680.  
  9681.  
  9682.  
  9683.  
  9684.  
  9685.  
  9686.  
  9687.  
  9688.  
  9689.  
  9690.  
  9691.  
  9692.  
  9693.  
  9694.  
  9695.  
  9696.  
  9697.                                          140
  9698.  
  9699.  
  9700.  
  9701.  
  9702.  
  9703.  
  9704.  
  9705.  
  9706.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9707.  
  9708.  
  9709.             
  9710.  
  9711.  
  9712.  
  9713.  
  9714.  
  9715.             scdrinfo  
  9716.  
  9717.  
  9718.  
  9719.  
  9720.             USAGE
  9721.                       signed int scdrinfo(
  9722.                            signed char handle,
  9723.                            signed int *reclen,
  9724.                            signed char *numflds,
  9725.                            void **ibfr,
  9726.                            void **obfr );
  9727.  
  9728.  
  9729.             PROTOTYPE IN
  9730.                       sc_base.h
  9731.  
  9732.  
  9733.             DESCRIPTION
  9734.                       scdrinfo gets the data record length "reclen", the
  9735.                       number of  data fields  per record  "numflds", and
  9736.                       the addresses  of  the  input  "ibfr"  and  output
  9737.                       "obfr" buffers.
  9738.  
  9739.  
  9740.             RETURN VALUE
  9741.                       SC_SUCCESS     requested information returned
  9742.                       SC_BADHNDL     data file not open or bad handle
  9743.                       SC_NULLPARM    parameter address null
  9744.  
  9745.  
  9746.             EXAMPLE
  9747.  
  9748.             #include "sc_base.h"
  9749.             
  9750.             void main()
  9751.             {
  9752.               char dbf, numflds;
  9753.               short reclen;
  9754.               void *ibfr, *obfr;
  9755.             
  9756.               scdinit(15);
  9757.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9758.                 scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr);
  9759.                 printf("Record length = %d\n",reclen);
  9760.  
  9761.  
  9762.  
  9763.                                          141
  9764.  
  9765.  
  9766.  
  9767.  
  9768.  
  9769.  
  9770.  
  9771.  
  9772.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9773.  
  9774.  
  9775.                 printf("Number of fields = %d\n",numflds);
  9776.                 printf("I/O buffers = %p %p\n",ibfr,obfr);
  9777.                 scddclose(dbf);
  9778.               }
  9779.               scdterm();
  9780.             }
  9781.  
  9782.  
  9783.  
  9784.  
  9785.  
  9786.  
  9787.  
  9788.  
  9789.  
  9790.  
  9791.  
  9792.  
  9793.  
  9794.  
  9795.  
  9796.  
  9797.  
  9798.  
  9799.  
  9800.  
  9801.  
  9802.  
  9803.  
  9804.  
  9805.  
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  
  9828.  
  9829.                                          142
  9830.  
  9831.  
  9832.  
  9833.  
  9834.  
  9835.  
  9836.  
  9837.  
  9838.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9839.  
  9840.  
  9841.             
  9842.  
  9843.  
  9844.  
  9845.  
  9846.  
  9847.             scdrput   
  9848.  
  9849.  
  9850.  
  9851.  
  9852.             USAGE
  9853.                       signed int scdrput(
  9854.                            signed char handle,
  9855.                            signed long *recno,
  9856.                            signed int howto );
  9857.  
  9858.  
  9859.             PROTOTYPE IN
  9860.                       sc_base.h
  9861.  
  9862.  
  9863.             DESCRIPTION
  9864.                       scdrput will  write the  data record  specified by
  9865.                       "recno" to  the data file associated with "handle"
  9866.                       from   the   internal   output   buffer.   "howto"
  9867.                       determines how the data record is to be written:
  9868.  
  9869.  
  9870.                       "howto" =      action
  9871.                         SC_ADD       append to end of file
  9872.                         SC_UPDATE    update current record
  9873.  
  9874.  
  9875.                       If a  record update  is occurring  the data record
  9876.                       number associated  with the  record in  the  input
  9877.                       buffer will  be returned.  An update  will not  be
  9878.                       performed  if  the  input  buffer  is  empty.  Use
  9879.                       scdrget/scdrcopy to  load a data record or scdfput
  9880.                       or scdfputs  to fill  the  data  record  field  by
  9881.                       field.
  9882.  
  9883.  
  9884.             SEE ALSO
  9885.                       scdfput, scdfputs, scdrget, scdrcopy.
  9886.  
  9887.  
  9888.             RETURN VALUE
  9889.                       SC_SUCCESS     record written
  9890.                       SC_BADHNDL     data file not open or bad handle
  9891.  
  9892.  
  9893.  
  9894.  
  9895.                                          143
  9896.  
  9897.  
  9898.  
  9899.  
  9900.  
  9901.  
  9902.  
  9903.  
  9904.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9905.  
  9906.  
  9907.                       SC_SKFAIL invalid data record number or disk seek
  9908.                                      failure
  9909.                       SC_WRTFAIL     disk write failure
  9910.                       SC_BADCMD invalid record write command
  9911.                       SC_NULLPARM    parameter address null
  9912.  
  9913.  
  9914.             EXAMPLE
  9915.  
  9916.             #include "sc_base.h"
  9917.             
  9918.             void main()
  9919.             {
  9920.               char dbf, logical = 'T', date[9] = "19881225";
  9921.               long recno;
  9922.               double numeric = 20.0L;
  9923.               unsigned long memo = 1L;
  9924.             
  9925.               scdinit(15);
  9926.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  9927.                 scdfputs(dbf,0,"SoftC Database Library   ");
  9928.                 scdfput(dbf,1,(void *) date);
  9929.                 scdfput(dbf,2,(void *) &logical);
  9930.                 scdfput(dbf,3,(void *) &memo);
  9931.                 scdfput(dbf,4,(void *) &numeric);
  9932.                 scdrput(dbf,&recno,SC_ADD);
  9933.                 printf("Record number = %ld\n",recno);
  9934.                 scddclose(dbf);
  9935.               }
  9936.               scdterm();
  9937.             }
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.  
  9947.  
  9948.  
  9949.  
  9950.  
  9951.  
  9952.  
  9953.  
  9954.  
  9955.  
  9956.  
  9957.  
  9958.  
  9959.  
  9960.  
  9961.                                          144
  9962.  
  9963.  
  9964.  
  9965.  
  9966.  
  9967.  
  9968.  
  9969.  
  9970.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  9971.  
  9972.  
  9973.             
  9974.  
  9975.  
  9976.  
  9977.  
  9978.  
  9979.             scdrundel 
  9980.  
  9981.  
  9982.  
  9983.  
  9984.             USAGE
  9985.                       signed int scdrundel(
  9986.                            signed char handle,
  9987.                            signed long recno );
  9988.  
  9989.  
  9990.             PROTOTYPE IN
  9991.                       sc_base.h
  9992.  
  9993.  
  9994.             DESCRIPTION
  9995.                       scdrundel will  remove the 'deleted' flag from the
  9996.                       data record specified by "recno".
  9997.  
  9998.  
  9999.             SEE ALSO
  10000.                       scdrdel.
  10001.  
  10002.  
  10003.             RETURN VALUE
  10004.                       SC_SUCCESS     record recovered
  10005.                       SC_BADHNDL     data file not open or bad handle
  10006.                       SC_SKFAIL invalid data record number or disk seek
  10007.                                      failure
  10008.                       SC_RDFAIL disk read failure
  10009.                       SC_WRTFAIL     disk write failure
  10010.  
  10011.  
  10012.             EXAMPLE
  10013.  
  10014.             #include "sc_base.h"
  10015.             
  10016.             void main()
  10017.             {
  10018.               char dbf;
  10019.               long recno;
  10020.             
  10021.               scdinit(15);
  10022.               if (scddopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
  10023.                 scdrundel(dbf,1L);
  10024.  
  10025.  
  10026.  
  10027.                                          145
  10028.  
  10029.  
  10030.  
  10031.  
  10032.  
  10033.  
  10034.  
  10035.  
  10036.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10037.  
  10038.  
  10039.                 scdrget(dbf,1L);
  10040.                 printf("%s\n",scemsg());
  10041.                 scddclose(dbf);
  10042.               }
  10043.               scdterm();
  10044.             }
  10045.  
  10046.  
  10047.  
  10048.  
  10049.  
  10050.  
  10051.  
  10052.  
  10053.  
  10054.  
  10055.  
  10056.  
  10057.  
  10058.  
  10059.  
  10060.  
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.  
  10067.  
  10068.  
  10069.  
  10070.  
  10071.  
  10072.  
  10073.  
  10074.  
  10075.  
  10076.  
  10077.  
  10078.  
  10079.  
  10080.  
  10081.  
  10082.  
  10083.  
  10084.  
  10085.  
  10086.  
  10087.  
  10088.  
  10089.  
  10090.  
  10091.  
  10092.  
  10093.                                          146
  10094.  
  10095.  
  10096.  
  10097.  
  10098.  
  10099.  
  10100.  
  10101.  
  10102.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10103.  
  10104.  
  10105.             
  10106.  
  10107.  
  10108.  
  10109.  
  10110.  
  10111.             scdtclose 
  10112.  
  10113.  
  10114.  
  10115.  
  10116.             USAGE
  10117.                       signed int scdtclose(
  10118.                            signed char handle );
  10119.  
  10120.  
  10121.             PROTOTYPE IN
  10122.                       sc_base.h
  10123.  
  10124.  
  10125.             DESCRIPTION
  10126.                       scdtclose  closes   a  memo  file  and  frees  all
  10127.                       allocated  memory   associated  with   memo   file
  10128.                       "handle".
  10129.  
  10130.  
  10131.             SEE ALSO
  10132.                       scdtopen.
  10133.  
  10134.  
  10135.             RETURN VALUE
  10136.                       SC_SUCCESS     memo file closed
  10137.                       SC_CLOSFAIL    file close failure
  10138.                       SC_BADHNDL     memo file not open or bad handle
  10139.  
  10140.  
  10141.             EXAMPLE
  10142.  
  10143.             #include "sc_base.h"
  10144.             
  10145.             void main()
  10146.             {
  10147.               char dbt;
  10148.             
  10149.               scdinit(15);
  10150.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS)
  10151.                 scdtclose(dbt);
  10152.               scdterm();
  10153.             }
  10154.  
  10155.  
  10156.  
  10157.  
  10158.  
  10159.                                          147
  10160.  
  10161.  
  10162.  
  10163.  
  10164.  
  10165.  
  10166.  
  10167.  
  10168.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10169.  
  10170.  
  10171.             
  10172.  
  10173.  
  10174.  
  10175.  
  10176.  
  10177.             scdtcreate     
  10178.  
  10179.  
  10180.  
  10181.  
  10182.             USAGE
  10183.                       signed int scdtcreate(
  10184.                            signed char *filename );
  10185.  
  10186.  
  10187.             PROTOTYPE IN
  10188.                       sc_base.h
  10189.  
  10190.  
  10191.             DESCRIPTION
  10192.                       scdtcreate creates a memo file. This function will
  10193.                       create a  new memo  file even  if one  had already
  10194.                       existed.
  10195.  
  10196.  
  10197.             RETURN VALUE
  10198.                       SC_SUCCESS     memo file created
  10199.                       SC_WRTFAIL     disk write failure
  10200.                       SC_BADFNAME    invalid filename
  10201.                       SC_NOHNDL no DOS file handles available
  10202.                       SC_NULLPARM    parameter address null
  10203.  
  10204.  
  10205.             EXAMPLE
  10206.  
  10207.             #include "sc_base.h"
  10208.             
  10209.             void main()
  10210.             {
  10211.               scdinit(15);
  10212.               scdtcreate("TEST.DBT");
  10213.               scdterm();
  10214.             }
  10215.  
  10216.  
  10217.  
  10218.  
  10219.  
  10220.  
  10221.  
  10222.  
  10223.  
  10224.  
  10225.                                          148
  10226.  
  10227.  
  10228.  
  10229.  
  10230.  
  10231.  
  10232.  
  10233.  
  10234.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10235.  
  10236.  
  10237.             
  10238.  
  10239.  
  10240.  
  10241.  
  10242.  
  10243.             scdterm   
  10244.  
  10245.  
  10246.  
  10247.  
  10248.             USAGE
  10249.                       signed int scdterm( void );
  10250.  
  10251.  
  10252.             PROTOTYPE IN
  10253.                       sc_base.h
  10254.  
  10255.  
  10256.             DESCRIPTION
  10257.                       scdterm is  called once at the end of the program.
  10258.                       Memory allocated  by scdinit  for internal control
  10259.                       structures will  be freed.  All files open will be
  10260.                       closed and  any memory  allocated for them will be
  10261.                       freed.
  10262.  
  10263.  
  10264.             SEE ALSO
  10265.                       scdinit.
  10266.  
  10267.  
  10268.             RETURN VALUE
  10269.                       SC_SUCCESS     completed shutdown
  10270.  
  10271.  
  10272.             EXAMPLE
  10273.  
  10274.             #include "sc_base.h"
  10275.             
  10276.             void main()
  10277.             {
  10278.               scdinit(15);
  10279.               scdterm();
  10280.             }
  10281.  
  10282.  
  10283.  
  10284.  
  10285.  
  10286.  
  10287.  
  10288.  
  10289.  
  10290.  
  10291.                                          149
  10292.  
  10293.  
  10294.  
  10295.  
  10296.  
  10297.  
  10298.  
  10299.  
  10300.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10301.  
  10302.  
  10303.             
  10304.  
  10305.  
  10306.  
  10307.  
  10308.  
  10309.             scdtinfo  
  10310.  
  10311.  
  10312.  
  10313.  
  10314.             USAGE
  10315.                       signed int scdtinfo(
  10316.                            signed char handle,
  10317.                            signed char *filename );
  10318.  
  10319.  
  10320.             PROTOTYPE IN
  10321.                       sc_base.h
  10322.  
  10323.  
  10324.             DESCRIPTION
  10325.                       scdtinfo gets the name of the memo file associated
  10326.                       with "handle".
  10327.  
  10328.  
  10329.             SEE ALSO
  10330.                       scdtopen.
  10331.  
  10332.  
  10333.             RETURN VALUE
  10334.                       SC_SUCCESS     file name returned
  10335.                       SC_BADHNDL     memo file not open or bad handle
  10336.                       SC_NULLPARM    parameter address null
  10337.  
  10338.  
  10339.             EXAMPLE
  10340.  
  10341.             #include "sc_base.h"
  10342.             
  10343.             void main()
  10344.             {
  10345.               char dbt, filename[13];
  10346.             
  10347.               scdinit(15);
  10348.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS) {
  10349.                 scdtinfo(dbt,filename);
  10350.                 printf("%s",filename);
  10351.                 scdtclose(dbt);
  10352.               }
  10353.               scdterm();
  10354.  
  10355.  
  10356.  
  10357.                                          150
  10358.  
  10359.  
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.  
  10366.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10367.  
  10368.  
  10369.             }
  10370.  
  10371.  
  10372.  
  10373.  
  10374.  
  10375.  
  10376.  
  10377.  
  10378.  
  10379.  
  10380.  
  10381.  
  10382.  
  10383.  
  10384.  
  10385.  
  10386.  
  10387.  
  10388.  
  10389.  
  10390.  
  10391.  
  10392.  
  10393.  
  10394.  
  10395.  
  10396.  
  10397.  
  10398.  
  10399.  
  10400.  
  10401.  
  10402.  
  10403.  
  10404.  
  10405.  
  10406.  
  10407.  
  10408.  
  10409.  
  10410.  
  10411.  
  10412.  
  10413.  
  10414.  
  10415.  
  10416.  
  10417.  
  10418.  
  10419.  
  10420.  
  10421.  
  10422.  
  10423.                                          151
  10424.  
  10425.  
  10426.  
  10427.  
  10428.  
  10429.  
  10430.  
  10431.  
  10432.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10433.  
  10434.  
  10435.             
  10436.  
  10437.  
  10438.  
  10439.  
  10440.  
  10441.             scdtopen  
  10442.  
  10443.  
  10444.  
  10445.  
  10446.             USAGE
  10447.                       signed int scdtopen(
  10448.                            signed char *handle,
  10449.                            signed char *filename );
  10450.  
  10451.  
  10452.             PROTOTYPE IN
  10453.                       sc_base.h
  10454.  
  10455.  
  10456.             DESCRIPTION
  10457.                       scdtopen  opens   a  memo  file.  Memory  will  be
  10458.                       allocated for  a file  packet and  I/O buffers for
  10459.                       use internally  by the  library file  manager. The
  10460.                       memo file  will be  tested as  much as possible to
  10461.                       insure that  it is  a  legitimate  dBASEIII+  memo
  10462.                       file.
  10463.  
  10464.  
  10465.             RETURN VALUE
  10466.                       SC_SUCCESS     memo file opened
  10467.                       SC_NULLPARM    parameter address null
  10468.                       SC_MEMERR memory allocation failure
  10469.                       SC_NOFILE memo file not found
  10470.                       SC_RDFAIL disk read failure
  10471.                       SC_NOHNDL no SoftC file handles available
  10472.                       SC_BADFNAME    invalid filename
  10473.                       SC_NODBT  file was not in memo format
  10474.  
  10475.  
  10476.             EXAMPLE
  10477.  
  10478.             #include "sc_base.h"
  10479.             
  10480.             void main()
  10481.             {
  10482.               char dbt;
  10483.             
  10484.               scdinit(15);
  10485.               if (scdtopen(&dbt,"TEST.DBT") == SC_SUCCESS)
  10486.  
  10487.  
  10488.  
  10489.                                          152
  10490.  
  10491.  
  10492.  
  10493.  
  10494.  
  10495.  
  10496.  
  10497.  
  10498.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10499.  
  10500.  
  10501.                 scdtclose(dbt);
  10502.               scdterm();
  10503.             }
  10504.  
  10505.  
  10506.  
  10507.  
  10508.  
  10509.  
  10510.  
  10511.  
  10512.  
  10513.  
  10514.  
  10515.  
  10516.  
  10517.  
  10518.  
  10519.  
  10520.  
  10521.  
  10522.  
  10523.  
  10524.  
  10525.  
  10526.  
  10527.  
  10528.  
  10529.  
  10530.  
  10531.  
  10532.  
  10533.  
  10534.  
  10535.  
  10536.  
  10537.  
  10538.  
  10539.  
  10540.  
  10541.  
  10542.  
  10543.  
  10544.  
  10545.  
  10546.  
  10547.  
  10548.  
  10549.  
  10550.  
  10551.  
  10552.  
  10553.  
  10554.  
  10555.                                          153
  10556.  
  10557.  
  10558.  
  10559.  
  10560.  
  10561.  
  10562.  
  10563.  
  10564.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10565.  
  10566.  
  10567.             
  10568.  
  10569.  
  10570.  
  10571.  
  10572.  
  10573.             scdvers   
  10574.  
  10575.  
  10576.  
  10577.  
  10578.             USAGE
  10579.                       signed char *scdvers( void );
  10580.  
  10581.  
  10582.             PROTOTYPE IN
  10583.                       sc_base.h
  10584.  
  10585.  
  10586.             DESCRIPTION
  10587.                       scdvers returns  a pointer  to the  SoftC Database
  10588.                       Library revision ASCIIZ string.
  10589.  
  10590.  
  10591.             RETURN VALUE
  10592.                       scdvers returns the library revision.
  10593.  
  10594.  
  10595.             EXAMPLE
  10596.  
  10597.             #include "sc_base.h"
  10598.             
  10599.             void main()
  10600.             {
  10601.               scdinit(15);
  10602.               printf("SoftC Database Library Revision %s",scdvers());
  10603.               scdterm();
  10604.             }
  10605.  
  10606.  
  10607.  
  10608.  
  10609.  
  10610.  
  10611.  
  10612.  
  10613.  
  10614.  
  10615.  
  10616.  
  10617.  
  10618.  
  10619.  
  10620.  
  10621.                                          154
  10622.  
  10623.  
  10624.  
  10625.  
  10626.  
  10627.  
  10628.  
  10629.  
  10630.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10631.  
  10632.  
  10633.             
  10634.  
  10635.  
  10636.  
  10637.  
  10638.  
  10639.             sceclr    
  10640.  
  10641.  
  10642.  
  10643.  
  10644.             USAGE
  10645.                       void sceclr( void );
  10646.  
  10647.  
  10648.             PROTOTYPE IN
  10649.                       sc_base.h
  10650.  
  10651.  
  10652.             DESCRIPTION
  10653.                       sceclr will clear the SoftC Database Library error
  10654.                       flag (sc_code).
  10655.  
  10656.  
  10657.             SEE ALSO
  10658.                       scemsg.
  10659.  
  10660.  
  10661.             RETURN VALUE
  10662.                       None.
  10663.  
  10664.  
  10665.             EXAMPLE
  10666.  
  10667.             #include "sc_base.h"
  10668.             
  10669.             void main()
  10670.             {
  10671.               scdinit(15);
  10672.               if ((scddopen(&dbf,"Customer.dbf") == SC_SUCCESS) &&
  10673.                   (scdnopen(&ndx1,"custcode.ndx") == SC_SUCCESS))
  10674.                 scdnopen(&ndx2,"custname.ndx");
  10675.               if (sc_code < SC_SUCCESS) {
  10676.                 select("Data files missing. Create new files
  10677.             (Y/N)","YN",&ch);
  10678.                 if (ch == 'Y') {
  10679.                   sceclr();
  10680.                   scddcreate("Customer.dbf",12,fields);
  10681.                   scdncreate("CUSTCODE.NDX",'N',"CODE",8);
  10682.                   scdncreate("CUSTNAME.NDX",'c',"lastname",25);
  10683.                   if ((scddopen(&dbf,"Customer.dbf") == SC_SUCCESS) &&
  10684.  
  10685.  
  10686.  
  10687.                                          155
  10688.  
  10689.  
  10690.  
  10691.  
  10692.  
  10693.  
  10694.  
  10695.  
  10696.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10697.  
  10698.  
  10699.                       (scdnopen(&ndx1,"custcode.ndx") == SC_SUCCESS))
  10700.                     scdnopen(&ndx2,"custname.ndx");
  10701.                   if (sc_code < SC_SUCCESS)
  10702.                     exit(1);
  10703.                 }
  10704.                 else
  10705.                   exit(1);
  10706.               }
  10707.               sceclr();
  10708.               scdterm();
  10709.             }
  10710.  
  10711.  
  10712.  
  10713.  
  10714.  
  10715.  
  10716.  
  10717.  
  10718.  
  10719.  
  10720.  
  10721.  
  10722.  
  10723.  
  10724.  
  10725.  
  10726.  
  10727.  
  10728.  
  10729.  
  10730.  
  10731.  
  10732.  
  10733.  
  10734.  
  10735.  
  10736.  
  10737.  
  10738.  
  10739.  
  10740.  
  10741.  
  10742.  
  10743.  
  10744.  
  10745.  
  10746.  
  10747.  
  10748.  
  10749.  
  10750.  
  10751.  
  10752.  
  10753.                                          156
  10754.  
  10755.  
  10756.  
  10757.  
  10758.  
  10759.  
  10760.  
  10761.  
  10762.                        CHAPTER 6, THE SOFTC DATABASE LIBRARY
  10763.  
  10764.  
  10765.             
  10766.  
  10767.  
  10768.  
  10769.  
  10770.  
  10771.             scemsg    
  10772.  
  10773.  
  10774.  
  10775.  
  10776.             USAGE
  10777.                       signed char *scemsg( void );
  10778.  
  10779.  
  10780.             PROTOTYPE IN
  10781.                       sc_base.h
  10782.  
  10783.  
  10784.             DESCRIPTION
  10785.                       scemsg returns  a pointer  to the  SoftC  Database
  10786.                       Library error or warning message which corresponds
  10787.                       to the code found in sc_code.
  10788.  
  10789.  
  10790.             SEE ALSO
  10791.                       sceclr.
  10792.  
  10793.  
  10794.             RETURN VALUE
  10795.                       scemsg returns the message text.
  10796.  
  10797.  
  10798.             EXAMPLE
  10799.  
  10800.             #include "sc_base.h"
  10801.             
  10802.             void main()
  10803.             {
  10804.               char dbf;
  10805.               scdinit(15);
  10806.               if (scdopen(&dbf,"TEST.DBF") != SC_SUCCESS)
  10807.                 printf("%s",scemsg());
  10808.               else
  10809.                 printf("File opened O.K.");
  10810.               scdterm();
  10811.             }
  10812.  
  10813.  
  10814.  
  10815.  
  10816.  
  10817.  
  10818.  
  10819.                                          157
  10820.  
  10821.  
  10822.  
  10823.  
  10824.  
  10825.  
  10826.  
  10827.  
  10828.           
  10829.  
  10830.  
  10831.             Appendix A
  10832.  
  10833.  
  10834.             Result Codes and Messages
  10835.  
  10836.  
  10837.  
  10838.  
  10839.             Warning Codes and Messages
  10840.  
  10841.             SC_DELREC 1    "WARNING - record read is marked deleted"
  10842.  
  10843.             The data  file record just read was flagged as "inactive" or
  10844.             "deleted". dBASE  retains "deleted"  records until  the data
  10845.             file is packed.
  10846.  
  10847.  
  10848.             SC_EMPTY  2    "WARNING - file is empty"
  10849.  
  10850.             You have  attempted to  read from an index file which has no
  10851.             keys (is empty).
  10852.  
  10853.  
  10854.             SC_END    3    "WARNING - no more keys"
  10855.  
  10856.             The current  key pointer  is located  at the physical end of
  10857.             the index  file, either at the first key or at the last key.
  10858.             The actual position depends upon the function called.
  10859.  
  10860.  
  10861.             SC_NOFIND 4    "WARNING - could not find key in index file"
  10862.  
  10863.             The index key supplied to the function could not be found in
  10864.             the index  file. Make sure that the index key is being built
  10865.             properly.
  10866.  
  10867.  
  10868.             SC_FLDTRUNC    5    "WARNING - data field truncated"
  10869.  
  10870.             The length  of the  data supplied  is larger  than the space
  10871.             allocated for  the field  in  the  data  file  record.  This
  10872.             usually occurs only with character type fields.
  10873.  
  10874.  
  10875.             SC_FLDROUND    6    "WARNING - numeric field rounded"
  10876.  
  10877.             Numeric data  is not  stored in  the data record in floating
  10878.             point format,  rather it  is converted  to  ASCII  and  then
  10879.             stored complete  with decimal  point. If  the numeric  value
  10880.             desired to  be written  is more  precise than  space in  the
  10881.  
  10882.  
  10883.  
  10884.  
  10885.                                          158
  10886.  
  10887.  
  10888.  
  10889.  
  10890.  
  10891.  
  10892.  
  10893.  
  10894.                        APPENDIX A, RESULT CODES AND MESSAGES
  10895.  
  10896.  
  10897.             field permits  the data  will be  rounded and  this  warning
  10898.             returned.
  10899.  
  10900.  
  10901.             SC_FILENGTH    7    "WARNING - file length is incorrect"
  10902.  
  10903.             After data,  index, or memo files are opened, the calculated
  10904.             file length is compared to the actual length. If they do not
  10905.             agree this  code is  returned. This  warning will occur most
  10906.             frequently with data files.
  10907.  
  10908.  
  10909.             Error Codes and Messages
  10910.  
  10911.             SC_WRTFAIL     -1   "ERROR - file write failure"
  10912.  
  10913.             This indicates a file write error of some sort. The disk may
  10914.             be full, the floppy drive door may be open, ... In this case
  10915.             a check of the compiler global variable errno should be made
  10916.             in order to determine the cause of the failure.
  10917.  
  10918.  
  10919.             SC_RDFAIL -2   "ERROR - file read failure"
  10920.  
  10921.             This indicates  a file  read error  of some sort. The global
  10922.             variable  errno  should  be  checked  to  help  isolate  the
  10923.             failure.
  10924.  
  10925.  
  10926.             SC_MEMERR -3   "ERROR - memory allocation error"
  10927.  
  10928.             An attempt  to allocate  memory  by  the  file  manager  has
  10929.             failed. This  failure could  be caused  by many  things: not
  10930.             enough memory  available, memory  threads corrupted, using a
  10931.             null pointer,  ... Check your code to ensure that you do not
  10932.             have a  problem in this area. You may have to go to a larger
  10933.             data model.
  10934.  
  10935.  
  10936.             SC_SKFAIL -4   "ERROR - file pointer reposition failed"
  10937.  
  10938.             This error  is returned under two circumstances: actual seek
  10939.             failed or  an attempt was made to seek beyond the end of the
  10940.             file in  a function  intending to  read after  seek. In  the
  10941.             first case  a check of errno may prove to be helpful. In the
  10942.             second case  you should verify the record number (for either
  10943.             data, index, or memo files) being requested is legitimate.
  10944.  
  10945.  
  10946.  
  10947.  
  10948.  
  10949.  
  10950.  
  10951.                                          159
  10952.  
  10953.  
  10954.  
  10955.  
  10956.  
  10957.  
  10958.  
  10959.  
  10960.                        APPENDIX A, RESULT CODES AND MESSAGES
  10961.  
  10962.  
  10963.             SC_NOFILE -5   "ERROR - file not found"
  10964.  
  10965.             You have attempted to open a data, index, or memo file which
  10966.             cannot be  found. If  you are certain the file exists, check
  10967.             the path specification.
  10968.  
  10969.  
  10970.             SC_FILBAD -6   "ERROR - file corrupted"
  10971.  
  10972.             The file  manager has noticed something seriously wrong with
  10973.             the index  file. Close  and reopen the file, it may still be
  10974.             good. Otherwise you will have to rebuild the index file.
  10975.  
  10976.  
  10977.             SC_BADEXPR     -7   "ERROR - bad user specified key
  10978.                                 expression"
  10979.  
  10980.             This indicates  an error  either  with  the  length  or  the
  10981.             contents of the expression. The length can be no larger than
  10982.             220 characters.  See scdkmake  for more information on valid
  10983.             expression content.
  10984.  
  10985.  
  10986.             SC_NOHNDL -8   "ERROR - no handles available"
  10987.  
  10988.             Either DOS  or the  file manager  has no  more  unused  file
  10989.             handles. Each  DOS application  is allowed to have a maximum
  10990.             of twenty files open (up to the total defined by "FILES=" in
  10991.             "CONFIG.SYS"). Five of these files are reserved for console,
  10992.             printer, etc.  which leaves  only fifteen available for you.
  10993.             scdinit can  be used  to specify the maximum number of SoftC
  10994.             Database Library files which can be open simultaneously.
  10995.  
  10996.  
  10997.             SC_NOPGS  -9   "ERROR - no index pages loaded"
  10998.  
  10999.             This is  an internal  file manager  error which should never
  11000.             occur. Contact SoftC, Ltd. if you get this error.
  11001.  
  11002.  
  11003.             SC_BADPG  -10  "ERROR - index page was not loaded"
  11004.  
  11005.             This is  an internal  file manager  error which should never
  11006.             occur. Contact SoftC, Ltd. if you get this error.
  11007.  
  11008.  
  11009.             SC_CLOSFAIL    -11  "ERROR - file close failure"
  11010.  
  11011.             This indicates  that DOS  could not properly close the file.
  11012.             Check errno for help in isolating further.
  11013.  
  11014.  
  11015.  
  11016.  
  11017.                                          160
  11018.  
  11019.  
  11020.  
  11021.  
  11022.  
  11023.  
  11024.  
  11025.  
  11026.                        APPENDIX A, RESULT CODES AND MESSAGES
  11027.  
  11028.  
  11029.             SC_BADCMD -12  "ERROR - invalid command"
  11030.  
  11031.             This error is a general purpose indicator. It means that the
  11032.             I/O buffer  selected, date  string translation  format, data
  11033.             file record  write type, or maximum number of resident index
  11034.             pages was invalid depending upon the function executed.
  11035.  
  11036.  
  11037.             SC_BADHNDL     -13  "ERROR - invalid handle number"
  11038.  
  11039.             The file  handle does  not match  the function required file
  11040.             type or  there is  no file open for that handle. For example
  11041.             this will  occur when using an index file handle with a data
  11042.             file function.
  11043.  
  11044.  
  11045.             SC_BADFNAME    -14  "ERROR - invalid filename"
  11046.  
  11047.             The length  of the  file name  was zero or the file name was
  11048.             invalid in  some other  way. The  file manager  expects file
  11049.             names to  be complete  with an  extension.  File  paths  are
  11050.             optional.
  11051.  
  11052.  
  11053.             SC_BADDATE     -15  "ERROR - invalid date"
  11054.  
  11055.             The year,  month, and/or day was invalid. Verify the date is
  11056.             correct.
  11057.  
  11058.  
  11059.             SC_BADTIME     -16  "ERROR - invalid time"
  11060.  
  11061.             The hour, minute, and/or second was invalid. Verify the time
  11062.             is correct.
  11063.  
  11064.  
  11065.             SC_NODBT  -17  "ERROR - file not in .DBT format"
  11066.  
  11067.             The memo  file length  was too  short. This  file cannot  be
  11068.             used.
  11069.  
  11070.  
  11071.             SC_DBFVERS     -18  "ERROR - invalid dBASE version"
  11072.  
  11073.             The dBASE  version  number  in  the  data  file  header  was
  11074.             unsupported. Only  dBASEIII, dBASEIII+, and dBASEIV versions
  11075.             are valid. This file cannot be used.
  11076.  
  11077.  
  11078.  
  11079.  
  11080.  
  11081.  
  11082.  
  11083.                                          161
  11084.  
  11085.  
  11086.  
  11087.  
  11088.  
  11089.  
  11090.  
  11091.  
  11092.                        APPENDIX A, RESULT CODES AND MESSAGES
  11093.  
  11094.  
  11095.             SC_DBFHLEN     -19  "ERROR - file header length error"
  11096.  
  11097.             The length  of the  dBASE header  was invalid. The length of
  11098.             the header  must be  divisible by  32 with  a  remainder  of
  11099.             either 0 or 1. This file cannot be used.
  11100.  
  11101.  
  11102.             SC_DBFDATE     -20  "ERROR - last file change date in error"
  11103.  
  11104.             The data  file header  last modified  date was invalid. This
  11105.             file cannot be used.
  11106.  
  11107.  
  11108.             SC_NULLPARM    -21  "ERROR - parameter address null"
  11109.  
  11110.             The address  of a parameter is NULL. Check the parameters on
  11111.             the call to ensure they are correct.
  11112.  
  11113.  
  11114.             SC_BADKEYT     -22  "ERROR - invalid key type"
  11115.  
  11116.             Only index  key types  of character  and  numeric  (includes
  11117.             dates) are supported. Make sure the key type is of 'C', 'D',
  11118.             or 'N'. All others are invalid.
  11119.  
  11120.  
  11121.             SC_KEYLEN -23  "ERROR - invalid key length"
  11122.  
  11123.             The character  key maximum  length  definition  exceeds  100
  11124.             characters. This  error does not occur for numeric (or date)
  11125.             keys.
  11126.  
  11127.  
  11128.             SC_ITEMLEN     -24  "ERROR - item length incorrect"
  11129.  
  11130.             The file  manager index  key item  length not agree with the
  11131.             value read from the index file. This file cannot be used.
  11132.  
  11133.  
  11134.             SC_BADROOT     -25  "ERROR - invalid root page"
  11135.  
  11136.             The index  page number  for the  top of  the Btree  does not
  11137.             exist in the index file. This file cannot be used.
  11138.  
  11139.  
  11140.             SC_MAXKEYS     -26  "ERROR - bad maximum number of keys per
  11141.                                 page"
  11142.  
  11143.             The file manager maximum number of index keys per index page
  11144.             does not agree with the value read from the index file. This
  11145.             file cannot be used.
  11146.  
  11147.  
  11148.  
  11149.                                          162
  11150.  
  11151.  
  11152.  
  11153.  
  11154.  
  11155.  
  11156.  
  11157.  
  11158.                        APPENDIX A, RESULT CODES AND MESSAGES
  11159.  
  11160.  
  11161.             SC_FLDCNT -27  "ERROR - invalid number of fields"
  11162.  
  11163.             A  data  file  record  can  consist  of  a  maximum  of  128
  11164.             individual fields.
  11165.  
  11166.  
  11167.             SC_BADFLDN     -28  "ERROR - field name invalid"
  11168.  
  11169.             The field  name length  cannot  exceed  ten  characters  not
  11170.             including the null bye.
  11171.  
  11172.  
  11173.             SC_FLDLEN -29  "ERROR - bad field length"
  11174.  
  11175.             Character fields  cannot be longer than 254 bytes. dBASE III
  11176.             numeric fields  cannot be  longer than  19 bytes.  dBASE  IV
  11177.             numeric and  float fields  cannot be  longer than  20 bytes.
  11178.             This error will not occur for the other field types.
  11179.  
  11180.  
  11181.             SC_DECPL  -30  "ERROR - decimal places parameter invalid"
  11182.  
  11183.             The  decimal   places  definition   portion  of   the  field
  11184.             description cannot be less than 0 nor can it be greater than
  11185.             the field length minus two.
  11186.  
  11187.  
  11188.             SC_BADFLDT     -31  "ERROR - invalid field type"
  11189.  
  11190.             Only character ('C'), date ('D'), logical ('L'), memo ('M'),
  11191.             and  numeric   ('N')  are   allowed  in   dBASE  III  files.
  11192.             Additionally, dBASE IV supports a floating point ('F') field
  11193.             type.
  11194.  
  11195.  
  11196.             SC_RECLEN -32  "ERROR - invalid record length"
  11197.  
  11198.             The record length cannot exceed 4000 bytes. Check your field
  11199.             lengths and make sure that they total 4000 or less.
  11200.  
  11201.  
  11202.             SC_BADDATA     -33  "ERROR - bad data"
  11203.  
  11204.             The data  you requested  to be written into a data field was
  11205.             invalid. For  example a pointer to a floating point variable
  11206.             was passed  for a  character field.  Ensure  the  data  type
  11207.             passed matches the field definition.
  11208.  
  11209.  
  11210.  
  11211.  
  11212.  
  11213.  
  11214.  
  11215.                                          163
  11216.  
  11217.  
  11218.  
  11219.  
  11220.  
  11221.  
  11222.  
  11223.  
  11224.                        APPENDIX A, RESULT CODES AND MESSAGES
  11225.  
  11226.  
  11227.             SC_LINELEN     -34  "ERROR - memo soft line length invalid"
  11228.  
  11229.             Valid values for line lengths are 0, and between 10 and 132.
  11230.             The line  length parameter  is used when the file manager is
  11231.             inserting soft  carriage returns  in  memo  text  as  it  is
  11232.             written to the memo file.
  11233.  
  11234.  
  11235.             SC_MDXFLAG     -35  "ERROR - MDX flag in DBF file invalid"
  11236.  
  11237.             The value  found in  byte twenty  eight (28)  of the dBASEIV
  11238.             data file  is not valid. Only values of zero (0) and one (1)
  11239.             are currently supported. This may indicate a corrupted file.
  11240.  
  11241.  
  11242.             Other Messages
  11243.  
  11244.             "Unknown error or warning code"
  11245.  
  11246.             This message  is returned  by scemsg  if it  cannot  find  a
  11247.             message which corresponds to the value found in sc_code. The
  11248.             function scemsg  may be  old or  otherwise incompatible with
  11249.             the value found in sc_code.
  11250.  
  11251.  
  11252.  
  11253.  
  11254.  
  11255.  
  11256.  
  11257.  
  11258.  
  11259.  
  11260.  
  11261.  
  11262.  
  11263.  
  11264.  
  11265.  
  11266.  
  11267.  
  11268.  
  11269.  
  11270.  
  11271.  
  11272.  
  11273.  
  11274.  
  11275.  
  11276.  
  11277.  
  11278.  
  11279.  
  11280.  
  11281.                                          164
  11282.  
  11283.  
  11284.  
  11285.  
  11286.  
  11287.  
  11288.  
  11289.  
  11290.           
  11291.  
  11292.  
  11293.             Appendix B
  11294.  
  11295.  
  11296.             Address List Program (DEMO1.C)
  11297.  
  11298.  
  11299.  
  11300.  
  11301.             The Address  List Program  is a  simple program  which  will
  11302.             create a  database (CUSTOMER.DBF)  and two  index files. The
  11303.             database record contains the following fields:
  11304.  
  11305.  
  11306.             field name  type  length description
  11307.             __________________________________________
  11308.             CODE        N     10.0   customer code
  11309.             DATE        D     8      date added to file
  11310.             FIRSTNAME   C     15     first name
  11311.             LASTNAME    C     25     last name
  11312.             COMPANY     C     40     company name
  11313.             ADDRESS     C     30     street address, po box, etc
  11314.             CITY        C     20     city
  11315.             STATE       C     2      state
  11316.             ZIPCODE     C     5      5 digit zip code
  11317.             AREACODE    C     3      telephone area code
  11318.             TELEPHONE   C     8      telephone number
  11319.             EXTENSION   C     4      telephone extension
  11320.  
  11321.  
  11322.             The index  files created  are: CUSTCODE.NDX (customer code),
  11323.             and CUSTNAME.NDX (customer last name).
  11324.  
  11325.  
  11326.             The program has two main functions: Update/Add new addresses
  11327.             and List  contents of  database. It  also supports  a "Quit"
  11328.             command.
  11329.  
  11330.  
  11331.             The Update  function enables the user to either add a new or
  11332.             find an existing record. The Add subfunction displays a data
  11333.             entry screen  and then  the user  steps through  the  fields
  11334.             filling the  blanks as  required (use  Control Z  to end Add
  11335.             mode). The  Find subfunction  allows the user to select what
  11336.             the search  type will be: CODE or LASTNAME. Once the data to
  11337.             be searched  for has  been entered, the user will be allowed
  11338.             to scroll  forward and  backward through the data. After the
  11339.             data record  has been  found, the user is allowed to edit or
  11340.             delete the data record (and keys).
  11341.  
  11342.  
  11343.  
  11344.  
  11345.  
  11346.  
  11347.                                          165
  11348.  
  11349.  
  11350.  
  11351.  
  11352.  
  11353.  
  11354.  
  11355.  
  11356.                        APPENDIX B, ADDRESS LIST DEMO PROGRAM
  11357.  
  11358.  
  11359.             The List  function allows the user to select where data will
  11360.             be displayed  (Printer/Screen) and  how  to  sort  the  data
  11361.             (Code/Name/Unsorted). The  "CODE", "LASTNAME", and "COMPANY"
  11362.             fields of each data record are displayed.
  11363.  
  11364.  
  11365.             Seventeen lines  of data are output to the screen as a page.
  11366.             The user  is then prompted to continue the display or abort.
  11367.             Data sent  to the  printer is continuous with no headings or
  11368.             page numbers.
  11369.  
  11370.  
  11371.             The program  as it  stands is  barely useable  as an address
  11372.             list manager  but its  real value is in the demonstration of
  11373.             certain library  functions. However, it could form the basis
  11374.             of a full featured address list manager, or ...
  11375.  
  11376.  
  11377.  
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  
  11384.  
  11385.  
  11386.  
  11387.  
  11388.  
  11389.  
  11390.  
  11391.  
  11392.  
  11393.  
  11394.  
  11395.  
  11396.  
  11397.  
  11398.  
  11399.  
  11400.  
  11401.  
  11402.  
  11403.  
  11404.  
  11405.  
  11406.  
  11407.  
  11408.  
  11409.  
  11410.  
  11411.  
  11412.  
  11413.                                          166
  11414.  
  11415.  
  11416.  
  11417.  
  11418.  
  11419.  
  11420.  
  11421.  
  11422.           
  11423.  
  11424.  
  11425.             Appendix C
  11426.  
  11427.  
  11428.             Diskette TOC Demo Program
  11429.  
  11430.  
  11431.  
  11432.  
  11433.             The Diskette  TOC Program  is a  simple program  which  will
  11434.             create a  database (TOC.DBF)  and  three  index  files.  The
  11435.             database record contains the following fields:
  11436.  
  11437.  
  11438.             field name  type  length description
  11439.             __________________________________________
  11440.             NAME        C     12     file name
  11441.             LENGTH      N     10.0   file size in bytes
  11442.             DATE        D     8      file creation date
  11443.             TIME        C     8      file creation time
  11444.             ATTRIBUTE   C     3      file attribute (READ ONLY, HIDDEN)
  11445.  
  11446.  
  11447.             The  index  files  created  are:  TOCNAME.NDX  (file  name),
  11448.             TOCLNGTH.NDX (file  length), and  TOCDATE.NDX (file creation
  11449.             date and time).
  11450.  
  11451.  
  11452.             The  program   uses  the   DOS  functions   "findfirst"  and
  11453.             "findnext" to  step through  the files  in the directory. It
  11454.             reformats the  compressed file  date ("mm/dd/yy")  and  time
  11455.             ("hh:mm:ss") and  places the  resultant data into the output
  11456.             buffer. After  all fields have been entered it will append a
  11457.             record to the end of the database and add keys for each file
  11458.             found.
  11459.  
  11460.  
  11461.             The program only works on the current directory. It does not
  11462.             support any  command line  arguments, although  it would  be
  11463.             easy for  the user  to add  such support.  Very little error
  11464.             checking is performed.
  11465.  
  11466.  
  11467.             The program as it stands has value only in the demonstration
  11468.             of certain  library functions.  However, it  could form  the
  11469.             basis of a diskette cataloger, or ...
  11470.  
  11471.  
  11472.  
  11473.  
  11474.  
  11475.  
  11476.  
  11477.  
  11478.  
  11479.                                          167
  11480.  
  11481.  
  11482.  
  11483.  
  11484.  
  11485.  
  11486.  
  11487.  
  11488.                                        Index
  11489.  
  11490.  
  11491.                                               sccds2n  17, 27, 34
  11492.             Data                                              sccdvalid  18, 24, 27, 36
  11493.               field                                              sccdxlat  17, 24, 37
  11494.                 array  52, 55, 78                                              sccleap  18, 39, 40
  11495.                 read                                              sccleapi  18, 39, 40
  11496.                   memo  72, 74                                              sccmonth  17, 23, 41
  11497.                   strings  68, 70                                              scctdiff  18, 43
  11498.                   values  66, 76                                              scctn2s  18, 43, 45, 47
  11499.                 write                                              sccts2n  18, 45, 47
  11500.                   memo  88, 90                                              scctvalid  18, 43, 45, 49
  11501.                   strings  84, 86                                              scddclose  12, 50
  11502.                   values  82, 92                                              scddcreate  12, 13, 52,
  11503.               file                                                  56
  11504.                 close  50                                              scddcreatex  53, 55
  11505.                 create  52, 55                                              scddinfo  12, 58, 60
  11506.                 I/O buffer clear  133                                              scddopen  12, 50, 58, 60,
  11507.                 I/O buffer copy  135                                                  63
  11508.                 information  58                                              scddopenx  60, 62
  11509.                 number of records  65                                              scddsize  12, 65
  11510.                 open  60, 62                                              scdfget  14, 66, 68, 72,
  11511.               record                                                  76, 77, 82, 84, 86,
  11512.                 delete  137                                                  92, 139
  11513.                 read  139                                              scdfgets  14, 67, 68, 70,
  11514.                 recover  145                                                  76, 84, 86, 92, 93
  11515.                 write  143                                              scdfgetsx  14, 68, 70, 77
  11516.                                               scdfgett  15, 66, 67, 72,
  11517.             Date                                                  74, 76, 88
  11518.               calculate                                              scdfgettx  15, 66, 67,
  11519.                 days per month  29, 31                                                  74, 76
  11520.                 difference  24                                              scdfgetx  14, 67, 70, 76
  11521.               test                                              scdfinfo  14, 66, 67, 68,
  11522.                 leap year  39, 40                                                  70, 77, 78
  11523.                 valid  36                                              scdfnam2no  14, 80
  11524.               translate                                              scdfput  14, 15, 67, 77,
  11525.                 string format  37                                                  82, 84, 86, 88, 92,
  11526.                 to integers  34                                                  93, 139, 143
  11527.                 to long  33                                              scdfputs  14, 68, 70, 82,
  11528.                 to string                                                  84, 86, 92, 93, 143
  11529.                   day of week  23                                              scdfputsx  84, 86
  11530.                   integers  27                                              scdfputt  15, 72, 88, 90
  11531.                   long  26                                              scdfputtx  15, 88, 90
  11532.                   month  41                                              scdfputx  14, 82, 92
  11533.                                               scdinit  3, 7, 19, 94,
  11534.             Functions                                                  149, 160
  11535.               sccday  17, 23, 41                                              scdkadd  16, 96, 103
  11536.               sccddiff  18, 24                                              scdkcur  16, 98
  11537.               sccdl2s  17, 26                                              scdkdate  16, 96, 100,
  11538.               sccdn2s  17, 24, 27, 34                                                  101, 113
  11539.               sccdperm  18, 29, 31                                              scdkdatex  16
  11540.               sccdpermi  18, 29, 31                                              scdkdel  16, 103
  11541.               sccds2l  17, 26, 33                                              scdkfind  16, 98, 105
  11542.  
  11543.  
  11544.  
  11545.                                         168
  11546.  
  11547.  
  11548.  
  11549.  
  11550.  
  11551.  
  11552.  
  11553.  
  11554.                                        INDEX
  11555.  
  11556.  
  11557.               scdkfirst  16, 98, 107                                                close  121
  11558.               scdklast  16, 98, 109                                                create  122
  11559.               scdkmake  16, 96, 111,                                                open  128
  11560.                   114, 123, 160                                              key
  11561.               scdkmakex  16, 113, 114                                                add  96
  11562.               scdknext  16, 98, 116                                                build  100, 101, 111,
  11563.               scdkprev  16, 98, 119                                                    114
  11564.               scdnclose  15, 121                                                delete  103
  11565.               scdncreate  15, 113, 122                                                get first  107
  11566.               scdnexpr  15, 124                                                get last  109
  11567.               scdninfo  15, 98, 105,                                                read next  116
  11568.                   106, 107, 109, 116,                                                read previous  119
  11569.                   119, 124, 126                                                search  105
  11570.               scdnopen  15, 126, 128                                              page count
  11571.               scdpinfo  16, 130                                                retrieve  130
  11572.               scdpnum  16, 131                                                set  131
  11573.               scdrclear  13, 133
  11574.               scdrcopy  13, 135, 143                                            Initialization  94
  11575.               scdrdel  13, 137, 145
  11576.               scdrget  13, 67, 68, 70,                                            Library version  154
  11577.                   77, 139, 143
  11578.               scdrinfo  13, 78, 141                                            Memo file
  11579.               scdrput  13, 139, 143                                              close  147
  11580.               scdrundel  13, 137, 145                                              create  148
  11581.               scdtclose  15, 147                                              open  152
  11582.               scdtcreate  15, 148                                              read  72, 74
  11583.               scdterm  7, 12, 19, 94,                                              write  88, 90
  11584.                   149
  11585.               scdtinfo  15, 150                                            Return codes
  11586.               scdtopen  14, 147, 150,                                              clear  155
  11587.                   152                                              defined  19, 158
  11588.               scdvers  19, 154                                              errors
  11589.               sceclr  20, 155, 157                                                SC_BADCMD  37, 71, 74,
  11590.               scemsg  19, 155, 157, 164                                                    77, 87, 93, 114,
  11591.                                                     131, 133, 135, 144,
  11592.             Global variables                                                    161
  11593.               sc_code  19, 20, 22, 155,                                                SC_BADDATA  83, 84, 87,
  11594.                   157, 164                                                    93, 163
  11595.               sc_softlen  15, 88                                                SC_BADDATE  23, 24, 26,
  11596.                                                     27, 29, 31, 33, 34,
  11597.             Index                                                    36, 37, 39, 40, 41,
  11598.               expression                                                    67, 68, 71, 77, 83,
  11599.                 defined  111, 122                                                    84, 86, 93, 100,
  11600.                 functions                                                    101, 161
  11601.                   dtoc  16, 111                                                SC_BADEXPR  113, 114,
  11602.                   left  16, 111, 112                                                    123, 160
  11603.                   right  16, 111, 112                                                SC_BADFLDN  53, 57, 61,
  11604.                   str  16, 111, 112                                                    63, 80, 113, 114,
  11605.                   substr  16, 111, 112                                                    163
  11606.                 read  124                                                SC_BADFLDT  53, 56, 61,
  11607.               file                                                    63, 163
  11608.  
  11609.  
  11610.  
  11611.                                         169
  11612.  
  11613.  
  11614.  
  11615.  
  11616.  
  11617.  
  11618.  
  11619.  
  11620.                                        INDEX
  11621.  
  11622.  
  11623.                 SC_BADFNAME  53, 56,                                                SC_NULLPARM  23, 24,
  11624.                     60, 63, 123, 128,                                                    26, 27, 29, 31, 33,
  11625.                     148, 152, 161                                                    34, 36, 37, 39, 40,
  11626.                 SC_BADHNDL  50, 58, 65,                                                    41, 43, 45, 47, 49,
  11627.                     67, 68, 70, 72, 74,                                                    53, 57, 58, 60, 63,
  11628.                     77, 79, 80, 83, 84,                                                    65, 67, 68, 71, 72,
  11629.                     86, 88, 90, 93, 94,                                                    74, 77, 79, 80, 83,
  11630.                     96, 98, 103, 106,                                                    84, 86, 88, 90, 93,
  11631.                     107, 109, 113, 114,                                                    96, 99, 100, 101,
  11632.                     116, 119, 121, 124,                                                    103, 106, 107, 109,
  11633.                     126, 130, 131, 133,                                                    113, 114, 117, 120,
  11634.                     135, 137, 139, 141,                                                    123, 124, 126, 128,
  11635.                     143, 145, 147, 150,                                                    130, 131, 141, 144,
  11636.                     161                                                    148, 150, 152, 162
  11637.                 SC_BADKEYT  123, 128,                                                SC_RDFAIL  60, 63, 72,
  11638.                     162                                                    74, 96, 98, 103,
  11639.                 SC_BADPG  160                                                    106, 107, 109, 117,
  11640.                 SC_BADROOT  128, 162                                                    120, 128, 137, 139,
  11641.                 SC_BADTIME  43, 45, 47,                                                    145, 152, 159
  11642.                     49, 161                                                SC_RECLEN  53, 57, 61,
  11643.                 SC_CLOSFAIL  50, 121,                                                    63, 163
  11644.                     147, 160                                                SC_SKFAIL  50, 60, 63,
  11645.                 SC_DBFDATE  60, 63, 162                                                    72, 74, 88, 90, 96,
  11646.                 SC_DBFHLEN  60, 63, 162                                                    98, 103, 106, 107,
  11647.                 SC_DBFVERS  57, 60, 63,                                                    109, 117, 120, 128,
  11648.                     161                                                    137, 139, 144, 145,
  11649.                 SC_DECPL  53, 57, 163                                                    159
  11650.                 SC_FILBAD  72, 74, 103,                                                SC_WRTFAIL  50, 53, 56,
  11651.                     160                                                    96, 103, 123, 137,
  11652.                 SC_FLDCNT  53, 56, 67,                                                    144, 145, 148, 159
  11653.                     68, 71, 77, 83, 84,                                              message translate  157
  11654.                     87, 93, 163                                              warnings
  11655.                 SC_FLDLEN  53, 57, 72,                                                SC_DELREC  139, 158
  11656.                     74, 163                                                SC_EMPTY  103, 106,
  11657.                 SC_ITEMLEN  128, 162                                                    107, 109, 158
  11658.                 SC_KEYLEN  123, 128,                                                SC_END  98, 107, 109,
  11659.                     162                                                    117, 120, 158
  11660.                 SC_LINELEN  88, 90, 164                                                SC_FILENGTH  61, 63,
  11661.                 SC_MAXKEYS  128, 162                                                    128, 159
  11662.                 SC_MDXFLAG  61, 63, 164                                                SC_FLDROUND  83, 85,
  11663.                 SC_MEMERR  60, 63, 72,                                                    87, 93, 158
  11664.                     74, 94, 96, 113,                                                SC_FLDTRUNC  83, 84,
  11665.                     114, 128, 152, 159                                                    87, 93, 158
  11666.                 SC_NODBT  152, 161                                                SC_NOFIND  103, 106,
  11667.                 SC_NOFILE  60, 63, 128,                                                    158
  11668.                     152, 160
  11669.                 SC_NOHNDL  53, 57, 60,                                            SC_2ASCII  37
  11670.                     63, 123, 128, 148,
  11671.                     152, 160                                            SC_2ASCIIL  37
  11672.                 SC_NOPGS  160
  11673.                                             SC_2DBASE  37
  11674.  
  11675.  
  11676.  
  11677.                                         170
  11678.  
  11679.  
  11680.  
  11681.  
  11682.  
  11683.  
  11684.  
  11685.  
  11686.                                        INDEX
  11687.  
  11688.  
  11689.             SC_ADD  143
  11690.  
  11691.             SC_ASCII  101
  11692.  
  11693.             SC_CRDELETE  74
  11694.  
  11695.             SC_CRUNCHNG  74
  11696.  
  11697.             SC_DB3  56
  11698.  
  11699.             SC_DB4  56
  11700.  
  11701.             SC_DBASE  101
  11702.  
  11703.             SC_DBFINFO  58, 62
  11704.  
  11705.             SC_EXACT  105
  11706.  
  11707.             SC_FIELD  52, 55, 78
  11708.  
  11709.             SC_FIRST  105, 106
  11710.  
  11711.             SC_INPUT  70, 76, 86, 92,
  11712.             114, 133, 135
  11713.  
  11714.             SC_OUTPUT  70, 76, 86, 92,
  11715.             114, 133, 135
  11716.  
  11717.             SC_UPDATE  143
  11718.  
  11719.             Termination  149
  11720.  
  11721.             Time
  11722.               calculation  43
  11723.               test  49
  11724.               translation  45, 47
  11725.  
  11726.  
  11727.  
  11728.  
  11729.  
  11730.  
  11731.  
  11732.  
  11733.  
  11734.  
  11735.  
  11736.  
  11737.  
  11738.  
  11739.  
  11740.  
  11741.  
  11742.  
  11743.                                         171
  11744.  
  11745.  
  11746.  
  11747.  
  11748.  
  11749.  
  11750.  
  11751.  
  11752.  
  11753.  
  11754.  
  11755.                  
  11756.  
  11757.  
  11758.  
  11759.  
  11760.  
  11761.  
  11762.  
  11763.  
  11764.  
  11765.  
  11766.  
  11767.  
  11768.  
  11769.  
  11770.  
  11771.  
  11772.  
  11773.  
  11774.  
  11775.  
  11776.  
  11777.  
  11778.  
  11779.  
  11780.  
  11781.  
  11782.  
  11783.  
  11784.  
  11785.  
  11786.  
  11787.  
  11788.  
  11789.  
  11790.  
  11791.  
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797.  
  11798.  
  11799.  
  11800.  
  11801.  
  11802.  
  11803.  
  11804.  
  11805.  
  11806.  
  11807.  
  11808.  
  11809.  
  11810.  
  11811.  
  11812.  
  11813.  
  11814.  
  11815.